Sphinx 文档：使用 autodoc 将 python 源分成多个部分

Question

我正在使用带有autodoc Sphinx 来记录我的来源。 假设我有一个文件pre_processing.py ，包含 3 个类。 我想在生成的 HTML 文件中有一个部分，像这样

Main
====
Topic1
------
blabla
Here is included class1 and class2 doc

Topic2
------
blibli
Here is included class3 doc

但是，到目前为止我所能管理的就是：

Main
====
Topic1
------
blabla
Here is a link to  class1 and class2 doc

Topic2
------
blibli
Here is a link to class3 doc

Here is cdumped class1, class2 and class3

请问如何实现？ 我是否必须放弃autodoc并手动填写我的 rst 文件？

Answer 1

您可以通过将大纲（和随附文本）放入模块本身的文档字符串中来做到这一点。 假设这是您的pre_processing.py ：

# yada yada license yada
"""
Main
====
Topic1
------
blabla

.. autoclass:: class1

.. autoclass:: class2

Topic2
------
blibli
Here is a link to class3 doc
"""

class class1(…):
    """
    docstring of class 1
    """

…

然后你可以简单地使用.. automodule:在你的.rst文件中：

.. automodule:: pre_processing

这将首先读取模块的文档字符串并从那里生成文档。 由于那里的 autoclass 指令，类也被记录在案。