使用部分在 Python 模块中构建 Sphinx autodoc 文档

Question

我正在尝试改进 python 模块的文档结构。

现在我有一个 Sphinxindex.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将以您在源文件中编写的任何顺序显示自动记录的成员。

另一种选择是交换整个内容并以文学/文档测试形式编写模块。我认为对此没有良好的标准支持，但doctest可能具有实用功能，可以让您将“文字文档”转换为接近可导入模块的内容。