sphinx文档：使用autodoc将python源拆分为多个部分

Question

我使用Sphinx和autodoc来记录我的来源。 假设我有一个文件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，并手动填写我的第一个文件？

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

首先会读取模块的docstring并从那里生成文档。由于那里有autoclass指令，所以也会记录这些类。