Sphinx autodoc не является достаточно автоматическим

Я пытаюсь использовать Sphinx для документирования проекта на 5 000+ в Python. Он имеет около 7 базовых модулей. Насколько я знаю, для использования autodoc мне нужно написать такой код для каждого файла в моем проекте:

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

Это слишком утомительно, потому что у меня много файлов. Было бы намного проще, если бы я мог просто указать, что я хочу, чтобы пакет "mods" был документирован. Затем Sphinx мог рекурсивно пройти через пакет и сделать страницу для каждого подмодуля.

Есть ли такая функция? Если бы не я мог написать script, чтобы сделать все .rst файлы, но это заняло бы много времени.

Ответы

Ответ 1

Вы можете проверить этот скрипт, который я сделал. Я думаю, что это может помочь вам.

Этот скрипт анализирует дерево каталогов в поисках модулей и пакетов python и создает файлы ReST соответствующим образом для создания документации кода с помощью Sphinx. Он также создает индекс модулей.

UPDATE

Этот скрипт теперь является частью Sphinx 1.1 как apidoc.

Ответ 2

Я не знаю, было ли у Sphinx расширение autosummary в то время, когда был задан исходный вопрос, но на данный момент вполне возможно настроить автоматическую генерацию такого рода без использования sphinx-apidoc или аналогичного script. Ниже приведены настройки, которые работают для одного из моих проектов.

  • Включите расширение autosummary (а также autodoc) в файле conf.py и установите для параметра autosummary_generate значение True. Этого может быть достаточно, если вы не используете пользовательские шаблоны *.rst. В противном случае добавьте каталог шаблонов для исключения списка, или autosummary попытается обработать их как входные файлы (что кажется ошибкой).

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
autosummary_generate = True
templates_path = [ '_templates' ]
exclude_patterns = ['_build', '_templates']

  • Используйте autosummary:: в дереве TOC в файле index.rst. В этом примере документация для модулей project.module1 и project.module2 будет сгенерирована автоматически и помещена в каталог _autosummary.

    PROJECT
=======

.. toctree::

.. autosummary::
   :toctree: _autosummary

   project.module1
   project.module2

  • По умолчанию autosummary будет генерировать только очень короткие сводки для модулей и их функций. Чтобы изменить это, вы можете поместить файл настраиваемого шаблона в _templates/autosummary/module.rst (который будет обрабатываться с помощью Jinja2):

    {{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}
    :members:

В заключение, нет необходимости хранить каталог _autosummary под контролем версий. Кроме того, вы можете называть его всем, что хотите, и поместить его в любом месте в исходном дереве (помещая его ниже _build не будет работать).

Ответ 3

В каждом пакете файл __init__.py может иметь компоненты .. automodule:: package.module для каждой части пакета.

Тогда вы можете .. automodule:: package и в основном делать то, что хотите.