构建 Sphinx 文档答案

【问题标题】：Structuring Sphinx documentation构建 Sphinx 文档
【发布时间】：2011-07-16 04:59:39
【问题描述】：

我已经开始使用 Sphinx 记录一个 Python 项目。这是我第一次使用它——我习惯了使用类似 JavaDoc 的语法的工具，我有一些疑问。

由于我希望文档出现在代码附近，因此我使用了.. automodule::、.. autoclass:: 和.. automethod:: 指令。所以我的文档结构如下：index.rst 包含目录和

.. automodule:: my_main_package

然后顶级 __init__.py 包含类似的指令

.. automodule:: some_subpackage

对于每个子包等等。最后每个模块都包含指令

.. autoclass:: some_class
    :members:

对于模块中的每个类。

这主要是可行的，但我得到的是一个单页文档，使用起来有点奇怪。

我应该如何组织我的文档以获得超链接文件树？也就是说，主包应该包含它自己的文档和每个子包的链接等等，直到每个模块都有自己的页面。

【问题讨论】：

标签： python python-sphinx

【解决方案1】：

我从评论 here 中找到了这个 autopackage script。它会根据包的结构生成必要的 .rst 文件。

旁注：我仍然觉得我遗漏了一些东西，因为我不敢相信像 Sphinx 这样的工具，它以最先进的 Python 文档工具而闻名，却缺少编写基本 API 文档的功能。因此，在接受我自己的答案之前，我将把问题留待一段时间。

【讨论】：

我自己刚刚遇到了这个问题。我觉得我也错过了一些东西。但这是对 DRY 原则的极大违反。为什么我要在 .rst 文件中复制整个模块结构？
请注意，该脚本现在是 Sphinx 的一个组成部分，称为 apidoc：sphinx-doc.org/man/sphinx-apidoc.html

【解决方案2】：

即使我不是这方面的专家，但我想我可以回答您在这里提出的问题（关于文档/ rst 文件的组织）。

您可能在这里遗漏的关键是不要在同一顶级 TOCs rst 文件中使用 autoclass/automodule/automethod 调用，此顶级文件应包含指向包含这些调用的其他 rst 文件的链接。

假设您在 doc 目录（和子目录）中拥有所有 rst 文件，

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1/index
    module_2/index

在包含顶级index.rst 的目录中，您将拥有名称为module_1 和module_2 的子目录。这些将具有index.rst（名称只是特定于示例），其中将包含.. automodule::、.. autoclass:: 和.. automethod::。它可以包含类似

:mod:`module_1`
---------------

..automodule:: module_1
    :show-inheritance:

.. autoclass:: module_1.MyClass

当然，这不是标准或理想的做事方式，我建议这样做是因为它更整洁。您也可以将所有带有模块/类/方法文档的 rst 文件放在与顶级 index.rst 相同的目录中，具有结构

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1
    module_2

并且相同的目录将包含文档文件module_1.rst、module_2.rst 等。路径与config.py 文件相对。

【讨论】：

感谢您的回答，但如果理解得好，这意味着将模块结构复制到一堆 rst 文件中，这远非理想。我的问题的重点是如何让Sphynx自己找到这个，这是我链接的脚本的任务。
@Andrea 我认为，复制结构不是必需的，这只是我的喜好，python docutils 和 rst 允许我们制作任何结构，我们只需要包含链接。也许我没有正确理解你的问题，但无论我理解什么，也许你不应该在 index.rst 中包含.. automodule::。
嗯，问题如下。我有一个 python 包，包括 Sphynx 格式的 API 文档。我希望能够提取此文档，但我不想为每个 python 文件手动创建一个 rst 文件——我认为这应该是 Sphynx 本身的任务。我怎样才能做到这一点？例如，在我的回答中，我链接了一个执行此任务的脚本。如果我正确理解您的答案，您建议手动执行此操作

【解决方案3】：

我绝不是 Sphinx 方面的专家，但从阅读 documentation 看来，您可以在子目录中包含 TOC 树。 The TOC tree page 还提供了有关树内路径的一些信息；您是否尝试过在树中使用路径？

【讨论】：

我也不是专家，所以我可能遗漏了一些非常基本的东西。但如果我理解正确，为了使用 TOC，我应该创建一堆 .rst 文件。所以我必须复制结构。相反，我没有创建额外的 .rst 文件：所有文档都在 Python 源代码中。如果我误解了您的回复，请纠正我。