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

Question

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

现在我有一个狮身人面像 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: Unexpected section title or transition.'

运行时出错 make HTML .

那么如何在不将文档从它记录的代码中移开的情况下获得所需的结构呢？

Answer 1

So how can I get the desired structure without moving documentation away from the code it documents?

停止使用自动模块并改用自动类/自动功能？这样，您可以根据需要制作和重组最终文档，而不会弄乱 Python 级别的源代码，并且文档字符串仍然是正确的事实来源。

或者，将您的模块拆分为子模块，每个子模块都会自动记录，并且可以具有格式化的模块级文档字符串。顺便说一下，您可能想要配置 autodoc_member_order因为它是 alphabetical默认情况下(因此将重新排序所有内容)。 bysource将以您在源文件中编写的任何顺序显示自动记录的成员。

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