自动生成所有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 递归解析一个包并自动为遇到的每个类/方法/函数生成文档，而无需手动列出每个类？

- Cerin

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生成一个完整的项目，然后会递归查找<module_path>（项目）中的Python模块。

- Daniel

---

apidoc命令没有生成index.rst文件...我有什么遗漏吗？ - guilhermecgs

@guilhermecgs 在使用sphinx-apidoc之前，通常会使用sphinx-quickstart生成index.rst和modules.rst文件。但是你也可以通过使用-F或-full标志仅使用sphinx-apidoc来生成这些文件。该标志将在生成的文件中包含完整的文档内容。 - bad_coder

Answer 2

也许 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 中。

- mzjn

---

这似乎更像是某个完全不相关项目的事后想法。甚至似乎没有关于该工具本身的任何使用文档。 - Cerin

只使用原始的 Sphinx 是无法实现您想要的功能的。需要使用其他工具，而 apigen.py 是一个不错的选择。无论它是“无关的”还是“后来想出来的”，都没有关系。虽然这个工具没有被精心打包和详细文档化，但它并不是非常复杂。从适应短的主脚本 build_modref_templates.py 开始。该脚本从 apigen.py 中导入了 ApiDocWriter 类，该类执行了所有的难活儿。 - mzjn

我担心这只是一个事后补充，因为它是神经影像库的附录，开发者的重点将放在神经影像上，而不是让apigen.py适用于普通用户。但是，你提到Sphinx不支持这种类型的自动化是有道理的。最终，我选择了https://bitbucket.org/etienned/sphinx-autopackage-script，专门用于此任务，尽管我相信apigen.py也可能适用。 - Cerin

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/*

并且

生成HTML

- macm

Answer 4

从Sphinx版本3.1（2020年6月）开始，如果您想使用sphinx.ext.autosummary显示摘要表，并且您可以使用新的:recursive:选项自动检测包中的每个模块，无论嵌套多深，以及自动生成该模块中的每个属性、类、函数和异常的文档。

请参见我的答案：https://dev59.com/TXE85IYBdhLWcg3wl0rF#62613202。

- James Leedham