使用章节组织Python模块中的Sphinx autodoc文档

Question

使用章节组织Python模块中的Sphinx autodoc文档

pythonpython-3.xpython-sphinxrestructuredtextautodoc

7

我正在尝试改进我的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时出现错误。

那么，我如何在不将文档与其所描述的代码分开的情况下获得所需的结构？

- 5Ke

1

Sphinx不允许在docstrings中使用任意的节标题。 sphinx.ext.napoleon扩展是解决此问题的一种方法。我不确定它能帮助多少，但它支持许多预定义的节标题。请参见http://www.sphinx-doc.org/en/stable/ext/napoleon.html。 - mzjn

1

@mzjn sphinx.ext.napoleon 看起来确实很有用，但我无法让它与我请求的类型的部分配合工作。 - 5Ke

3

模块级别的文档字符串可以包含多个段落，但每个模块只能有一个这样的文档字符串。一个模块的__doc__属性是该模块中第一条语句作为字符串字面值的文本。请参见此被拒绝的Sphinx增强建议链接：https://github.com/sphinx-doc/sphinx/issues/442。 - mzjn

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Masklinn · Accepted Answer

那么我如何在不将文档移开代码的情况下获得期望的结构呢？停止使用automodule，而使用autoclass / autofunction即可。这样，您可以随意制作和重新组织文档的最终结构，而不会干扰Python级别的源代码，同时docstrings仍然是正确的真相来源。

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

另一个选择是完全交换，并以文学/ doctest形式编写模块。我认为这种方法没有很好的标准支持，但doctest可能具有实用功能，可以将“文学文档”转换为接近可导入模块的内容。