自动生成所有Python包内容的文档

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

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

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

我在子包中定义了几十个类和函数。然而，当我跑步时：

sphinx-build -b html . ./_build

报告说：

updating environment: 1 added, 0 changed, 0 removed

这似乎无法导入我的包中的任何内容。查看生成的index.html在“Contents:”旁边没有显示任何内容。索引页仅显示“mypackage（module）”，但单击它也显示它没有任何内容

---

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

也许apigen.py可以提供帮助：

此处对该工具进行了非常简要的描述：

或者更好的是，使用

---

---

更新：该实用程序已添加到Sphinx中。

您可以尝试使用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 quickstart生成一个完整的项目，并在（项目）中递归查找Python模块

希望这有帮助

注意

对于Sphinx（实际上是执行 Sphinx）要找到您的模块，它必须是可导入的。也就是说 模块或包必须位于上的一个目录中 sys.path–相应地调整配置文件中的sys.path

因此，转到conf.py并添加

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

现在您的index.rst看起来像：

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

Contents:

.. toctree::
   :maxdepth: 2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

.. automodule:: alphabuyer
   :members:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

及

从Sphinx 3.1版（2020年6月）开始制作html

，如果您愿意使用

Sphinx.ext.autosummary

显示摘要表，您可以使用新的

：recursive:

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

---

请看我的回答：

这似乎更像是对一些完全无关的项目的事后思考。甚至没有任何工具本身的使用文档，也没有办法只使用vanilla Sphinx。还需要做更多的工作，apigen.py是一个很好的候选者。为什么它是“无关”还是“事后思考”那么重要？该工具没有整齐的包装和详细的文档记录，但也不是非常复杂。首先调整简短的主脚本build_modref_templates.py。这个脚本从apigen.py导入ApiDocWriter类，完成了所有的艰苦工作。我担心这是事后的想法，因为它是神经成像库的补充，开发人员的重点将是神经成像，而不是让apigen.py为普通公众工作。然而，您关于Sphinx不支持这种类型的自动化的观点是正确的。我最终使用了，它专门用于此任务，尽管我确信apigen.py可能也可以工作。apidoc命令不会生成index.rst文件。。。我遗漏了什么吗？@guilhermecgs

index.rst

和

模块。rst

通常在使用

sphinx apidoc

之前使用

sphinx quickstart

生成。您可以仅使用

sphinx apidoc

生成这些文件，方法是使用。

.. toctree::
   :glob:

   example
   an_example_pypi_project/*