Я пытаюсь автоматически создавать API-документы для большой кодовой базы Python, используя Sphinx.

Я пытался использовать build_modules.py и sphinx-apidoc. С помощью любого из них я могу получить первые документы, успешно созданные в моей выходной директории для пакетов и модулей верхнего уровня.

Тем не менее, когда я строю с использованием

make html

это дает тысячи ошибок этого типа:

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

для каждого класса и метода в кодовой базе. Поэкспериментировав, я обнаружил, что директивы autosummary / autoclass создают тектоды, которые ожидают, что для каждого класса и метода будут первые файлы.

Помимо предупреждений, документация, кажется, работает хорошо, но я хотел бы избавиться от них, и я думаю, что я что-то неправильно настроил.

Я также пыталсяnipype / инструменты к тому же эффекту.

Я модифицировалapigen.py а такжеbuild_modref_templates.py создать первые заглушки для каждого из этих «отсутствующих» документы с автоклассом / автофункцией / автометодами в зависимости от ситуации. Однако сборка занимает довольно много времени (10 минут) и в конечном итоге дает сбой из-за ошибок памяти на последнем этапе сборки.

Вот пример первого файла модуля, который создает все предупреждения:

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:

Спасибо за любой совет о том, как разрешить эти предупреждения! Я хотел бы держаться подальше от любого решения, которое включает изменение файлов пакета сайта sphinx.