Может ли Sphinx autodoc документировать namespace.module без документирования пространства имен?

Кодовая база, с которой я работаю, структурирована по схеме namespace. Я отвечаю за namespace.my_project, но я завишу от различных других модулей из namespace. Есть ли способ указать Sphinx (с autodoc) документировать namespace.my_project, но игнорировать все непосредственно под namespace?

Я попытался добавить именно тот модуль, который хочу index.rst:

.. toctree::
    namespace.my_project

Это хорошо видно в окончательной документации, но во время компиляции я все еще получаю много предупреждений от членов namespace, которые я не могу контролировать.


python python-sphinx autodoc
person csiz    schedule 21.09.2016    source источник
comment
О чем предупреждения? Вы не можете просто игнорировать их?   -  person mzjn    schedule 26.09.2016
comment
Поскольку другие проекты в пространстве имен используют другие настройки sphinx, я получаю предупреждения, пытаясь их задокументировать (не подтверждая numpydoc и другие). Пока я должен игнорировать их, но я не доволен этим, так как очень трудно обнаружить предупреждения о моем собственном коде.   -  person csiz    schedule 27.09.2016

Ответы (1)


arrow_upward
0
arrow_downward

Для этого не так много вариантов, используя расширение autodoc, оно импортирует ваши объекты с обычными правилами импорта Python.

sphinx.ext.autodoc — включить документацию из строк документации

Это расширение может импортировать модули, которые вы документируете, и полуавтоматически извлекать документацию из строк документации.

Таким образом, вам придется выборочно писать файлы .rst, используя директивы autodoc, которые импортируют только то, что вы хотите. В вашем примере, предполагая, что my_project структурирован как пакет, это может быть относительно легко, вы должны написать:

.. automodule:: namespace.my_project

или скажем, у вас есть 2 разных пакета в пределах my_project

.. automodule:: namespace.my_project.my_package1

.. automodule:: namespace.my_project.my_package2

По сути, вы импортировали из проекта только те модули/объекты, которые вас интересуют. Тогда в директиву .. toctree:: вы должны включить только .rst файлов, в которых есть эти тщательно подобранные директивы.

Однако у этого есть несколько недостатков: все объекты в пространстве имен, которые вы явно не задокументировали, не будут включены в индекс и не будут иметь перекрестных ссылок (если только вы не создали пустые объявления .rst с директивы домена). Однако они будут отображаться в текстовом виде без ссылок, и при условии отсутствия основных ошибок Python документация будет построена нормально без предупреждений.

person bad_coder    schedule 24.03.2021