在Python模块中构造Sphinx autodoc文档

我试图改进python模块文档的结构

现在我有一个Sphinx

index.rst

文件，看起来像这样：

Contents:

.. toctree::
:maxdepth: 3

.. automodule:: myModule1
    :members:

.. automodule:: myModule2
    :members:

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

这将生成一个HTML页面，其中包含我所有文档化函数的一长串混乱列表。这意味着文档在代码中比在HTML输出中更容易阅读

第一个改进很简单：我可以在每个模型的开头添加标题和描述，这样在html输出中模块的视觉分离就更清晰了。所以像这样：

Contents:

.. toctree::
:maxdepth: 3

.. automodule:: myModule1
    :members:

.. automodule:: myModule2
    :members:

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

时出错

那么，我如何才能在不将文档从其文档的代码中移开的情况下获得所需的结构呢

那么，我如何才能在不将文档从其文档的代码中移开的情况下获得所需的结构呢

停止使用自动模块，改用自动类/自动功能？这样，您就可以随心所欲地编写和重新组织最终文档，而不会弄乱Python级别的源代码，而docstring仍然是正确的事实来源

或者，将模块拆分为子模块，每个子模块都会自动记录，并且可以具有格式化的模块级docstring。顺便说一句，您可能希望将

autodoc\u成员\u顺序

配置为默认的

字母顺序

（因此将对所有内容重新排序）

bysource

将按您在源文件中写入的顺序显示自动记录的成员

---

另一种选择是交换整个内容，并以读写/博士测试的形式编写模块。我认为没有很好的标准支持，但是

doctest

可能有一些实用功能，可以让您将“可读文档”转换为接近可导入模块的内容。

Sphinx不允许在docstring中使用任意节头。

sphinx.ext.poleon

扩展是解决这个问题的一种方法。我不确定它对您有多大帮助，但它支持许多预定义的节标题。请参阅。@mzjn

sphinx.ext.napoleon

看起来确实很有用，但我无法让它与我请求的节类型一起工作。在模块级文档字符串中可能有节。但每个模块只能有一个这样的docstring。模块的

\uuuu doc\uuuu

属性是作为模块中第一条语句出现的字符串文本。另请参见此被拒绝的Sphinx增强建议：。