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

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

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

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

Разъяснение: Вместо:

.. 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.

Ответ 1

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

.. automodule:: module
   :members:

Ответ 2

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

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

Я являюсь оригинальным автором этого script.

UPDATE

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

Ответ 3

Etienne script, упомянутый в его ответе, теперь интегрирован в Sphinx как sphinx-apidoc. Он делает именно то, чего хочет OP. Он запланирован для выпуска в 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>.

Ответ 4

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

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

Ответ 5

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

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

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