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 指令，類也被記錄在案。