Sphinx 文档：使用 autodoc 将 python 源代码拆分为多个部分答案

【问题标题】：Sphinx documentation: split a python source into sections, using autodocSphinx 文档：使用 autodoc 将 python 源代码拆分为多个部分
【发布时间】：2015-08-20 12:49:37
【问题描述】：

我正在使用带有 autodoc 的 Sphinx 来记录我的来源。假设我有一个文件pre_processing.py，其中包含 3 个类。我想在生成的 HTML 文件中有部分，像这样

Main
====
Topic1
------
blabla
Here is included class1 and class2 doc

Topic2
------
blibli
Here is included class3 doc

但是，到目前为止，我所能做的就是：

Main
====
Topic1
------
blabla
Here is a link to  class1 and class2 doc

Topic2
------
blibli
Here is a link to class3 doc

Here is cdumped class1, class2 and class3

请问如何实现？我必须放弃autodoc，并手动填写我的第一个文件吗？

【问题讨论】：

我不确定我是否理解这个问题，但如果您使用autoclass（为单个类生成文档）而不是automodule，它可能会按照您的意愿工作。跨度>
是的，如果我使用 autoclass，那么我可以编辑 rst 文件并根据需要使用 autoclass 构建我的部分。但我想以某种方式定义python源代码中的部分。 Liek 说“这个类属于 x 部分，这个属于 y 部分，等等”。

标签： python python-sphinx autodoc

【解决方案1】：

您可以通过将大纲（和随附的文本）放入模块本身的文档字符串中来做到这一点。假设这是你的pre_processing.py：

# yada yada license yada
"""
Main
====
Topic1
------
blabla

.. autoclass:: class1

.. autoclass:: class2

Topic2
------
blibli
Here is a link to class3 doc
"""

class class1(…):
    """
    docstring of class 1
    """

…

然后您可以在您的.rst 文件中简单地使用.. automodule:：

.. automodule:: pre_processing

这将首先读取模块的文档字符串并从那里生成文档。由于其中的 autoclass 指令，这些类也被记录在案。

【讨论】：