python - 使用 autodoc 的 Sphinx 文档 : split a python source into sections,

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
    """

…

然后您只需在 .rst 文件中使用 .. automodule: 即可:

.. automodule:: pre_processing

这将首先读取模块的文档字符串并从那里生成文档。由于其中的自动类指令，这些类也被记录下来。