在带有部分的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

但是这导致一个：

'SEVERE：意外的节标题或过渡。

运行make HTML时出错。

因此，如何在不将文档移离它所记录的代码的情况下获得所需的结构？

Answer 1

因此，如何在不将文档移离它所记录的代码的情况下获得所需的结构？