构建Sphinx文档

2022-04-21 00:00:00 python python-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文档的功能。因此,在接受我自己的答案之前,我将把这个问题保留一段时间。

相关文章