Автоматическое создание документации для всего содержимого пакета 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 рядом с «Содержание:» ничего не отображается.На индексной странице отображается только «mypackage (module)», но при нажатии на нее видно, что у нее также нет содержимого.

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

Answer 1

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

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

Или еще лучше, используйте документ.

---

Обновлять:тот сфинкс-апидок утилита добавлена ​​в Sphinx версия 1.1.

Answer 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, чтобы создать весь проект DOC, как это:

$ sphinx-apidoc -F -o docs project

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

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

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