python - 为所有 Python 包内容自动生成文档

Question

我正在尝试使用 Sphinx 为我的代码库自动生成基本文档。但是，我在指示 Sphinx 递归扫描我的文件时遇到了困难。

我有一个 Python 代码库，其文件夹结构如下:

<workspace>
└── src
    └── mypackage
        ├── __init__.py
        │   
        ├── subpackageA
        │   ├── __init__.py
        │   ├── submoduleA1
        │   └── submoduleA2
        │   
        └── subpackageB
            ├── __init__.py
            ├── submoduleB1
            └── submoduleB2

我在 <workspace> 中运行 sphinx-quickstart ，所以现在我的结构看起来像:

<workspace>
├── src
│   └── mypackage
│       ├── __init__.py
│       │
│       ├── subpackageA
│       │   ├── __init__.py
│       │   ├── submoduleA1
│       │   └── submoduleA2
│       │
│       └── subpackageB
│           ├── __init__.py
│           ├── submoduleB1
│           └── ubmoduleB2
│
├── index.rst
├── _build
├── _static
└── _templates  

我已阅读 quickstart tutorial ，尽管我仍在尝试理解文档，但它的措辞让我担心 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 混合使用，以便像这样创建整个 doc 项目:

$ sphinx-apidoc -F -o docs project

此调用将使用 sphinx-quickstart 生成一个完整的项目，并在 Python 模块的 (项目)中递归查找。