Сфинкс Автодок не хватает автоматического

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

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

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

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

4 121
python python-sphinx

4 ответа:

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

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

обновление

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

118

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

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

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

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

    PROJECT
=======

.. toctree::

.. autosummary::
   :toctree: _autosummary

   project.module1
   project.module2

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

    {{ fullname }}
{{ underline }}

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

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

28

В каждой упаковке, может быть .. automodule:: package.module компоненты для каждой части пакета.

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

11

может, то, что вы ищете-это Epydoc и расширение Сфинкс.

1