Question

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

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

.. automodule:: my_main_package

然后顶级__init__.py包含

等指令

.. automodule:: some_subpackage

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

.. autoclass:: some_class
    :members:

为模块中的每个类。

这大部分都有效，但我得到的是单页文档，这有点奇怪。

如何组织文档以获取超链接文件树？也就是说，主程序包应该包含自己的文档和每个子包的链接，依此类推，直到每个模块都有自己的页面。

Answer 1

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

旁注：我仍然觉得我遗漏了一些东西，因为我无法相信像Sphinx这样的工具，它被称为最先进的Python文档工具，它错过了执行基本API文档的功能。因此，在接受我自己的答案之前，我会暂时搁置这个问题。

Answer 2

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

此处可能缺少的密钥不是在同一顶级TOC的第一个文件中使用autoclass / automodule / automethod调用，此顶级文件应包含指向包含这些调用的其他第一个文件的链接

假设您在doc dir（和子目录）中有所有第一个文件，

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，Table of contents ================= The contents of the docs are: .. toctree:: :maxdepth: 1 module_1 module_2和module_1.rst。它可以包含类似

的内容

module_2.rst

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

config.py

并且相同的目录将包含文档文件{{1}}，{{1}}等。路径<{>>相对到{{1}}文件。

Answer 3

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

构建Sphinx文档

3 个答案: