构建Sphinx文档结构

Question

我开始用Sphinx来记录一个Python项目的文档。这是我第一次使用它，以前我习惯用那种像JavaDoc的语法工具，所以有些地方不太明白。

因为我希望文档能和代码放在一起，所以我用到了.. automodule::、.. autoclass::和.. automethod::这些指令。所以我的文档结构是这样的：index.rst里有目录，

.. automodule:: my_main_package

然后顶层的__init__.py里包含了一些指令，比如

.. automodule:: some_subpackage

针对每个子包，依此类推。最后，每个模块里也包含了指令

.. autoclass:: some_class
    :members:

针对模块里的每个类。

这样做大体上是有效的，但我得到的却是一个单页的文档，这样用起来有点奇怪。

我应该怎么组织我的文档，才能得到一个有超链接的文件树呢？也就是说，主包应该有自己的文档，并且链接到每个子包，直到每个模块都有自己的页面。

Answer 1

我并不是Sphinx方面的专家，但通过阅读文档，我发现你可以在子目录中包含目录树。目录树页面也提供了一些关于树中路径的信息；你有没有尝试过在树中使用路径呢？

Answer 2

虽然我也不是这方面的专家，但我觉得我可以回答你关于文档和rst文件组织的问题。

你可能忽略了一个关键点，那就是不要在同一个顶层的TOC的rst文件中使用autoclass、automodule和automethod这些调用，而是应该在这个顶层文件中放一些链接，指向其他包含这些调用的rst文件。

假设你把所有的rst文件都放在doc文件夹（以及子文件夹）里，

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文件的相对路径。

Answer 3

我在一个评论中找到了这个自动打包脚本，链接在这里。这个脚本可以根据你包的结构生成所需的 .rst 文件。

顺便说一下：我觉得我还是缺少了一些东西，因为我不敢相信像 Sphinx 这样被认为是最先进的 Python 文档工具，居然没有基本的 API 文档生成功能。所以我会先把这个问题保持开放状态，等一段时间再考虑接受我自己的答案。