Sphinx Python文档管理

Tags
Last edited time
Aug 16, 2025 01:07 PM
Sphinx是一款在Python社区中广泛采用的文档生成器，用于创建全面且结构清晰的项目文档。它由Python编写，是Python项目文档的事实标准。

sphinx-quickstart初始化项目

使用sphinx-quickstart 快速初始化，在项目中会生成docs 文件夹。可以看到一些基础的配置。安装myst可以解析mardown文档而不仅仅是rst文档。

快速创建API文档

我一开始上手的时候感觉整个框架非常的不清晰，感觉是从一个静态网站生成器迁移来的。从代码中自动获取docstring来生成带有结构文档有两种方法。都需要使用到自带的autodoc插件。
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",  # for Google/NumPy style docstrings
    "sphinx.ext.viewcode",
    "myst_parser",
]
autosummary_generate = True
conf.py

1. sphinx-apidoc

sphinx-apidoc 是一个用于自动生成Sphinx源文件的工具，它使用autodoc扩展，能够对整个包进行文档化。
它最大的定位是帮助你根据包的结构生成相应的rst文件。比如说，你的包里很多子包，它能够把每个子包都递归的创建stub（rst文件），并使用automodule 来创建详细文档。
sphinx-apidoc -o docs/source/api your_package
执行完后，会在docs/source/api 生成大量的rst文件。然后需要进一步的build，来生成文档。

2. autosummary

autosummary 是一个用在文档中的指令，它可以帮助你在当前页面生成一张表，并对表里的每一个子项生成一个页面。结合:recursive: 选项的话，也能够生成一个包里的结构。
.. autosummary::
   :toctree: generated
   :recursive:
   :nosignatures:

   your_package
它会在docs/source/generated 文件夹下面生成相关的stub 。但是要注意的是官方定义autosummary 的:recursive: 主要是针对包，它在叶节点不会对类和函数生成相应的stub （这也太坑了点…）