为所有 Python 包内容自动生成文档答案

【问题标题】：Automatically Generating Documentation for All Python Package Contents为所有 Python 包内容自动生成文档
【发布时间】：2011-01-06 15:44:02
【问题描述】：

我正在尝试使用 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 递归解析包并自动为其遇到的每个类/方法/函数生成文档，而不必自己手动列出每个类？

【问题讨论】：

标签： python python-sphinx documentation-generation sphinx-apidoc

【解决方案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 模块的（项目）中递归查找。

【讨论】：

apidoc 命令不生成 index.rst 文件...我错过了什么吗？
@guilhermecgs index.rst 和 modules.rst 通常在使用 sphinx-apidoc 之前使用 sphinx-quickstart 生成。您可以使用-F or -full flags 仅使用sphinx-apidoc 生成这些文件。

【解决方案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 version 1.1。

【讨论】：

这似乎更像是一些完全不相关的项目的事后想法。该工具本身似乎没有任何使用文档。
没有办法只用香草狮身人面像做你想做的事。需要更多的东西，apigen.py 是一个很好的候选者。为什么它是“无关的”或“事后的想法”很重要？该工具没有整齐地包装和精心记录，但也不是非常复杂。首先调整简短的主脚本 build_modref_templates.py。此脚本从 apigen.py 导入 ApiDocWriter 类，该类完成了所有艰苦的工作。
我担心这是事后的想法，因为由于它是神经影像库的附录，因此开发人员的重点将放在神经影像学上，而不是让 apigen.py 与公众一起使用。但是，您关于 Sphinx 不支持这种类型的自动化的观点是正确的。我最终选择了bitbucket.org/etienned/sphinx-autopackage-script，它专门用于这项任务，尽管我确信 apigen.py 可能也可以工作。

【解决方案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

【讨论】：

【解决方案4】：

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

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

【讨论】：