在带有部分的Python模块中构建Sphinx autodoc文档

问题描述 投票:4回答:1

我正在尝试改善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时出错。

因此,如何在不将文档移离它所记录的代码的情况下获得所需的结构?

python python-3.x python-sphinx restructuredtext autodoc
1个回答
1
投票

因此,如何在不将文档移离它所记录的代码的情况下获得所需的结构?

© www.soinside.com 2019 - 2024. All rights reserved.