使用部分

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

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

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

或者，将您的模块分成子模块，每个子模块都会自动记录文档，并且可以具有格式化的模块级文档字符串。顺便说一句，您可能希望将autodoc_member_order配置为默认的alphabetical（因此将重新排序所有内容）。 bysource将按照您在源文件中写入自动记录成员的顺序显示它们。

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