构建Sphinx文档

问题描述

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

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

.. automodule:: my_main_package

然后顶级__init__.py包含类似

的指令

.. automodule:: some_subpackage

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

.. autoclass:: some_class
    :members:

对于模块中的每个类。

这在很大程度上是有效的，但我得到的是单页文档，使用起来有点奇怪。

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

---

解决方案

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

旁注：我仍然觉得我遗漏了一些东西，因为我不敢相信像Sphinx这样的工具，作为记录Python的最先进的工具，会缺少做基本API文档的功能。因此，在接受我自己的答案之前，我将把这个问题保留一段时间。