Sphinx autosummary "toctree содержит ссылку на несуществующий документ" предупреждения

Я пытаюсь автоматически создавать 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.

Ответы

Ответ 1

Извините за такой поздний ответ (если можно это считать), но я нашел эту ссылку, которая обсуждает, что может произойти с вами:

https://github.com/phn/pytpm/issues/3#issuecomment-12133978

Идея о том, что если у вас есть какой-то специальный скребок Doc в вашем коде документации, который создает сборку документации по autosummary после того, как autosummary уже запущен, может возникнуть проблема, если вы все еще сталкиваетесь с этой проблемой. Хотя, я не уверен, насколько это поможет.

Ключ от ссылки состоит в том, чтобы добавить: numpydoc_show_class_members = False в conf.py

Ответ 2

Если вы используете расширение numpydoc, вы можете удалить его и использовать вместо него sphinx.ext.napoleon.

Начиная с версии 1.3, это встроенное расширение фактически поддерживает строки документов в стиле Numpy и Google.

numpydoc удаление numpydoc и использование sphinx.ext.napoleon в вашем conf.py, вероятно, решит вашу проблему.

источники

Ответ 3

Я только что столкнулся с этой проблемой и трачу на это часы, у меня сработало следующее:

Sphinx can be fussy, and sometimes about things you werent expecting. 
For example, you well encounter something like:

WARNING: toctree contains reference to nonexisting document u'all-about-me'
...
checking consistency...
<your repository>/my-first-docs/docs/all-about-me.rst::
WARNING: document isn't included in any toctree'

Quite likely, what has happened here is that you indented all-about-me
in your .. toctree:: with four spaces, when Sphinx is expecting three.

Источник: документы !