我正在尝试改善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
时出错。
因此,如何在不将文档移离它所记录的代码的情况下获得所需的结构?
因此,如何在不将文档移离它所记录的代码的情况下获得所需的结构?