在帶有部分的 Python 模塊中構建 Sphinx autodoc 文檔

Question

我正在嘗試改進我的 python 模塊的文檔結構。

現在我有一個 Sphinx index.rst文件，看起來像這樣：

Contents:

.. toctree::
:maxdepth: 3

.. automodule:: myModule1
    :members:

.. automodule:: myModule2
    :members:

等等。這會生成一個 HTML 頁面，其中包含我所有記錄的功能的長長的混亂列表。 這意味着文檔在代碼中比在 HTML 輸出中更容易閱讀。

第一個改進很簡單：我可以在每個模型的開頭添加標題和描述，這樣模塊的視覺分離在 html 輸出中變得更加清晰。 所以像這樣：

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""

等等，但現在我想更進一步，將我的模塊分成幾個部分，這些部分有自己的部分標題和屬於模塊功能子集的描述。 我嘗試了以下方法：

"""
##############################################
myModule1 Title
##############################################
Description of myModule1.
"""
... # meaning import statements etc
"""
**********************************************
First Section title
**********************************************
Some descriptive text
"""
def myFunction1()
    """ function doc """
    ... # meaning the actual function implementation

def myFunction2()
    """ function doc """
    ... # meaning the actual function implementation

"""
**********************************************
Second Section title
**********************************************
Some descriptive text
"""
def myFunction3()
    """ function doc """
    ...  # meaning the actual function implementation

def myFunction4()
    """ function doc """
    ...  # meaning the actual function implementation

但這會導致：

“嚴重：意外的部分標題或過渡。”

運行make HTML時出錯。

那么如何在不將文檔從它所記錄的代碼中移走的情況下獲得所需的結構呢？

Answer 1

那么如何在不將文檔從它所記錄的代碼中移走的情況下獲得所需的結構呢？

停止使用 automodule 並使用 autoclass/autofunction 代替？ 這樣你就可以隨意制作和重組你的最終文檔，而不會弄亂 Python 級別的源代碼，並且文檔字符串仍然是正確的事實來源。

或者，將您的模塊拆分為子模塊，每個子模塊都會自動記錄，並且可以具有格式化的模塊級文檔字符串。 順便說一句，您可能希望將autodoc_member_order配置為默認alphabetical （因此會重新排序所有內容）。 bysource將按照您在源文件中編寫的任何順序顯示自動記錄的成員。

另一種選擇是交換整個內容並以 literate / doctest 形式編寫模塊。 我不認為對此有很好的標准支持，但doctest可能具有實用功能，可讓您將“文字文檔”轉換為接近可導入模塊的內容。