Автоматическое создание документации для всех компонентов пакета Python

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

У меня есть кодовая база Python со структурой папок вроде:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2

Я запускал sphinx-quickstart в <workspace>, поэтому теперь моя структура выглядит так:

<workspace>
    src
        mypackage
            __init__.py
            subpackageA
                __init__.py
                submoduleA1
                submoduleA2
            subpackageB
                __init__.py
                submoduleB1
                submoduleB2
    index.rst
    _build
    _static
    _templates

Я прочитал учебник quickstart http://sphinx.pocoo.org/tutorial.html, и хотя я все еще пытаюсь понять документы, то, как он сформулировал, заставляет меня беспокоиться о том, что Sphinx предполагает Я собираюсь вручную создавать файлы документации для каждого отдельного модуля/класса/функции в моей кодовой базе.

Однако я заметил оператор "automodule", и я включил autodoc во время быстрого запуска, поэтому я надеюсь, что большая часть документации может быть сгенерирована автоматически. Я изменил свой conf.py, чтобы добавить мою папку src в sys.path, а затем модифицировал мой index.rst для использования automodule. Итак, теперь мой index.rst выглядит так:

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. automodule:: alphabuyer
   :members:

У меня есть десятки классов и функций, определенных в подпакетах. Тем не менее, когда я запускаю:

sphinx-build -b html . ./_build

он сообщает:

updating environment: 1 added, 0 changed, 0 removed

И это, кажется, не удалось импортировать что-либо внутри моего пакета. Просмотр сгенерированного index.html ничего не показывает рядом с "Содержание:". На странице Index отображается только "mypackage (module)", но нажатие на нее показывает, что оно также не содержит содержимого.

Как вы направляете Sphinx для рекурсивного анализа пакета и автоматически генерируете документацию для каждого класса/метода/функции, с которой он сталкивается, без необходимости вручную вручную перечислять каждый класс?

Ответ 1

Возможно, apigen.py может помочь: https://github.com/nipy/nipy/tree/master/tools.

Этот инструмент очень кратко описан здесь: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

Или еще лучше, используйте pdoc.

Обновление: утилита sphinx-apidoc была добавлена в Sphinx версии 1.1.

Ответ 2

Вы можете попробовать использовать sphinx-apidoc.

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

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

Вы можете смешать sphinx-apidoc с sphinx-quickstart, чтобы создать весь проект документа следующим образом:

$ sphinx-apidoc -F -o docs project

Этот вызов будет генерировать полный проект с помощью sphinx-quickstart и искать рекурсивно в (проекте) для модулей Python.

Надеюсь, это поможет!

Ответ 3

Примечание

Для Sphinx (фактически, интерпретатор Python, который выполняет Sphinx), чтобы найти ваш модуль, он должен быть импортируемым. Что означает, что модуль или пакет должны находиться в одной из каталогов на sys.path - адаптируйте свой sys.path в файле конфигурации соответственно

Итак, перейдите в свой conf.py и добавьте

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

Теперь ваш index.rst выглядит так:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

и

make html