自动生成所有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(模块)",但单击它显示它也没有内容.

如何指导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混合使用,以便创建整个doc项目,如下所示:

$ 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（实际上是执行Sphinx的Python解释器）找到您的模块，它必须是可导入的。这意味着模块或软件包必须位于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