Автодокументирование Python с использованием Sphinx

Question

Это обобщенная версия предыдущего вопроса о сфинксе .

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

Я думаю, что глупо добавлять директиву autofunction или automodule для каждой функции; Должен быть способ автоматизировать процесс, иначе я вообще не вижу смысла в использовании Сфинкса.

Пояснение: Вместо:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. automethod:: Seg.method_1

        .. automethod:: Seg.method_2

        .. automethod:: Seg.method_3

        .......

        .. automethod:: Seg.method_n

Для этого требуется, чтобы я вручную вырезал и вставлял имена всех методов и соответственно обновлял документацию. Мне нужна команда типа

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. MAGIC COMMAND: Automatically print the docstrings and signatures 
           of all Seg() methods.

Answer 1

Мы используем

.. automodule:: module
   :members:

Answer 2

Чтобы упростить задачу, вы можете использовать этот скрипт (смотрите последнюю версию внизу страницы): http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx

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

Я оригинальный автор этого сценария.

UPDATE

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

Answer 3

Сценарий Этьена, упомянутый в его ответе, теперь включен в Sphinx как sphinx-apidoc. Он делает именно то, что хочет ОП. Он планируется выпустить в Sphinx 1.1 или доступен в репозитории Hg:

https://bitbucket.org/birkenfeld/sphinx

Это прекрасно работает для меня. Документы читаются так:

> sphinx-apidoc --help
Usage: sphinx-apidoc-script.py [options] -o <output_path> <module_path>
           [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
a reST file with automodule directives per package in the <output_path>.

Answer 4

Я думаю, что глупо добавлять директиву автофункции или автомодуля для каждой функции; Должен быть способ автоматизировать процесс, иначе я вообще не вижу смысла в использовании Сфинкса.

Я бы предложил Epydoc , который специализируется на генерации документации из строк документации.

Answer 5

Вы хотите сделать это проще, чем просто указать автомодуль? Даже для большой библиотеки требуется 5 минут, чтобы набрать все имена модулей.

Причина этого в том, что Сфинкс с трудом догадывается, что нужно документировать.

Вы также можете написать autopackage, который будет искать модули и использовать директиву автомодуля (если автомодуль этого не делает).