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

Question

Я пытаюсь автоматически сгенерировать основную документацию для моей базы кода, используя 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

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

Однако я заметил инструкцию "automodule" и включил autodoc во время быстрого запуска, поэтому я 'Я надеюсь, что большая часть документации может быть сгенерирована автоматически.Я изменил свой conf.py, чтобы добавить папку src в sys.path, а затем изменил свой index.rst для использования автомодуля.Так что теперь мой 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 ничего не показывает рядом с «Contents:».На странице «Указатель» отображается только «mypackage (module)», но если щелкнуть по нему, он также не содержит содержимого.

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

Answer 1

Вы можете попробовать использовать 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.

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

Answer 2

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

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

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

---

Обновление: в Sphinx версия 1.1 .

была добавлена ​​утилита sphinx-apidoc .

Answer 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