自动生成所有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
│           └── ubmoduleB2
│
├── index.rst
├── _build
├── _static
└── _templates

我已经阅读了快速入门教程，尽管我仍在尝试理解文档，但措辞的方式让我担心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（模块）”，但单击它显示也没有内容。

您如何指导Sphinx递归解析程序包并为它遇到的每个类/方法/函数自动生成文档，而不必自己手动列出每个类？

Answer 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版中添加。