自动锁定您的代码¶

Sphinx AutoDoc扩展（请参见 http://www.sphinx-doc.org/en/stable/ext/autodoc.html ）在sphinx构建时，将python代码中的docstring转换为最终的文档格式。

这是非常有用的，但可能不会开箱即用。以下是正确设置的一些步骤：

告诉AutoDoc如何查找代码¶

没有一点帮助，AutoDoc可能找不到您的代码。编辑docs/source/conf.py文件。取消注释：

import os
import sys

取消注释并编辑此行（根据需要调整路径）：

sys.path.insert(0, os.path.abspath('../../<PROJECT_NAME>'))

如果您有子模块，那么您可能需要使用此路径：

sys.path.insert(0, os.path.abspath('../..'))

有一个脚本，您可以运行它为每个Python模块创建一个指令文件。只应运行此命令一次以设置 * .rst文件。

在docs目录中，运行此命令创建记录python模块的RST文件（注意-f选项告诉它覆盖现有文件）：

sphinx-apidoc -f -o source/ ../<PROJECT_NAME>/

您应该看到在docs/source/folder中创建的RST文件

docs/source中python模块的restructuredtext文件不包含docstring。相反，它们只包含关于如何构建相应页面的指令。

它们包含重构的dtext，其中包含从项目中的特定python模块构建文档的指令。例子：

example_module module
=====================

.. automodule:: example_module
    :members:
    :undoc-members:
    :show-inheritance:

此项目中的示例，显示带有结果HTML的源RST和Python：

重构文本：
example_module.rst

Python ：
example_module.py

自动生成的HTML:
example_module.html

以下是您可能希望添加的一些附加指令，包括：

使用这些额外指令的示例：

重构文本：
example_module2.rst

Python ：
example_module2.py

自动生成的HTML:
example_module2.html

虽然可以在python代码的docstrings中使用restructuredtext，但作者更喜欢使用纯文本。纯文本文档字符串仍然可以用autodoc生成伟大的HTML页面。最终，这是你的选择。