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

Question

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

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

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

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

Answer 1

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

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

UPDATE

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

Answer 2

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

1. Включите расширение 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']
   

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

   PROJECT
   =======
   
   .. toctree::
   
   .. autosummary::
      :toctree: _autosummary
   
      project.module1
      project.module2
   

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

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

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

Answer 3

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

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

Answer 4

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