Próbuję automatycznie utworzyć dokumentację api dla dużego kodu Pythona za pomocą Sphinx.

Próbowałem użyć build_modules.py i sphinx-apidoc. Z każdym z nich mogę uzyskać pierwsze dokumenty pomyślnie utworzone w moim katalogu wyjściowym dla pakietów i modułów najwyższego poziomu.

Jednak gdy buduję za pomocą

make html

daje tysiące błędów tego typu:

<autosummary>:None: WARNING: toctree contains reference to nonexisting document 'rstDocs/src.Example1.class1.method1'

dla każdej pojedynczej klasy i metody w bazie kodu. Z pewnymi eksperymentami myślę, że odkryłem, że dyrektywy autosummary / autoclass tworzą toctrees, które oczekują, że będą pierwsze pliki dla każdej klasy i metody.

Poza ostrzeżeniami dokumentacja wydaje się działać dobrze, ale chciałbym się ich pozbyć i myślę, że mogłem coś źle skonfigurować.

Próbowałem teżnipype / tools do tego samego efektu.

zmodyfikowałemapigen.py ibuild_modref_templates.py aby utworzyć pierwsze odgałęzienia dla każdego z tych „brakujących” dokumentów, odpowiednio z autoclass / autofunction / automethods. Jednak budowa trwa dość długo (10 minut) i ostatecznie ulega awarii z powodu błędów pamięci w ostatnim kroku kompilacji.

Oto przykładowy pierwszy plik modułu, który tworzy wszystkie ostrzeżenia:

src Package
===========

:mod:`src` Package
------------------

.. automodule:: src.__init__
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example1` Module
------------------------------------

.. automodule:: src.Example1
    :members:
    :undoc-members:
    :show-inheritance:

:mod:`Example2` Module
------------------

.. automodule:: src.Example2
    :members:
    :undoc-members:
    :show-inheritance:

Dziękujemy za wszelkie porady, jak rozwiązać te ostrzeżenia! Chciałbym trzymać się z daleka od wszelkich rozwiązań, które wymagają modyfikacji plików pakietu sfinksa.