自动生成所有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  

我已经阅读了快速入门教程，尽管我仍在尝试理解文档，但它的措辞方式让我担心 Sphinx 假设我将为每个模块/类/函数手动创建文档文件在我的代码库中。

但是，我确实注意到了“automodule”语句，并且我在快速启动期间启用了autodoc，所以我希望大部分文档可以自动生成。我修改了我的conf.py以将我的src文件夹添加到sys.path，然后修改我的index.rst以使用automodule。所以现在我的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:”旁边没有显示任何内容。 Index页面只显示“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

Answer 4

从 Sphinx 版本 3.1（2020 年 6 月）开始，如果您愿意使用

sphinx.ext.autosummary

显示汇总表，您可以使用新的

:recursive:

选项自动检测包中的每个模块，无论嵌套有多深，并自动生成该模块中每个属性、类、函数和异常的文档。

在这里查看我的答案：https://stackoverflow.com/a/62613202/12014259

Answer 5

Libris 也是一个很棒的文档生成器。使用 Libris，您只需指定主项目目录，它将递归扫描该目录以查找代码文件。

通过将文档字符串放置在您想要记录的函数或类之上，它的工作方式非常简单。

/*  @docs:
 *  @title: Load
 *  @description: Load a file.
 *  @parameter:
 *      @name: path
 *      @description: The path of the file.
 *  @parameter:
 *      @name: opts
 *      @description: The options for loading the file.
 *      @attribute:
 *          @name: encoding
 *          @description: The encoding to used for reading the file data.
 *      @attribute:
 *          @name: type
 *          @description: Cast the loaded data type to a specified type.
 *  @usage:
 *      await load("./myfile.txt");
 */
async function load(path, opts = {}) { ... }

要为整个代码库生成文档，您只需在根目录中创建一个名为

config.json

或

libris.json

的配置文件。

{
    "name": "My Project",
    "include": [
        "load.js", // also accepts directories here.
    ],
    "output_path": "docs.html"
}

导航到根目录并使用 libris cli 生成文档。

$ libris --generate

更多信息可以在文档中找到。