Токтри автосуммирования Sphinx содержит ссылку на предупреждения несуществующего документа.

Я пытаюсь автоматически создавать 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 создают toctrees, которые ожидают, что будут первые файлы для каждого класса и метода.

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

Я также пробовал 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.


python python-2.7 python-sphinx toctree sphinx-napoleon
person user1287170    schedule 30.08.2012    source источник
comment
Вы уверены, что у вас есть запись toctree, указывающая на сгенерированные документы? например к документации по src пакету, которую вы разместили выше?   -  person Kevin Horn    schedule 07.12.2012
comment
Связанная нерешенная проблема: github.com/numpy/numpydoc/issues/69   -  person taper    schedule 20.06.2018

Ответы (3)


arrow_upward
43
arrow_downward

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

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

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

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

person djhoese    schedule 04.03.2013
comment
Если вы это сделаете, таблица методов будет удалена :( - person Andreas Mueller; 27.10.2016
comment
Кто-нибудь обнаружил решение, которое не удаляет таблицу методов? Я не могу переключиться на sphinx.ext.napoleon, потому что, похоже, он не поддерживает ту же функцию, что и numpydoc_use_plots. - person Aaron Voelker; 25.05.2017
comment
›Кто-нибудь обнаружил решение, которое не удаляет таблицу методов? Да, скопируйте файл matplotlib / sphinxext / plot_directive.py в локальный каталог документа и используйте его как дополнительную директиву sphinx. - person Alex Kaszynski; 27.06.2021

arrow_upward
11
arrow_downward

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

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

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

Источники

person Kurt Bourbaki    schedule 05.04.2017

arrow_upward
7
arrow_downward

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

Сфинкс может быть суетливым, а иногда и о вещах, которых вы не ожидали. Например, вы можете встретить что-то вроде:

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'

Вполне вероятно, что здесь произошло то, что вы сделали отступ «все обо мне» в своем .. toctree:: четырьмя пробелами, в то время как Сфинкс ожидает трех.

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

person 0x78f1935    schedule 20.05.2019