Я пытаюсь автоматически создавать api docs для большой кодовой базы 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/tools с тем же эффектом.
Я изменил 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.