Sphinx生成Python文档的关键是代码与文档协同演进。需配置autodoc插件、规范docstring（推荐Google/NumPy风格）、用.rst组织结构、自动化构建发布，确保文档真实可维护。
用 Sphinx 生成高质量 Python 文档并不难，关键在于理清流程、配置合理、内容可维护。它不是写完代码再“补文档”，而是让文档和代码一起生长。
从项目结构开始：让 Sphinx 找得到你的代码
Sphinx 默认不自动读取 Python 源码，需要借助 sphinx.ext.autodoc 插件配合正确的模块路径。确保你的项目有清晰的包结构（含 red">__init__.py），并在 conf.py 中设置：
- sys.path.insert(0, os.path.abspath('../src')) —— 把源码根目录加进 Python 路径（假设源码在 ../src）
- extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] —— 启用自动提取 docstring 和跳转源码功能
- autodoc_default_options = {'members': True, 'undoc-members': True} —— 控制哪些成员默认显示
用 docstring 写文档：简洁规范才真正好用
Sphinx 依赖 docstring 生成 API 文档，推荐使用 Google 风格 或 NumPy 风格（比纯 reStructuredText 更易读、易维护）。例如：
def add(a: int, b: int) -> int:
"""两整数相加。
Args:
a: 第一个加数
b: 第二个加数
Returns:
相加结果
Example:
>>> add(2, 3)
5
"""
return a + b
这样写，autodoc 就能解析出参数、返回值、示例，并渲染成结构化网页。
立即学习“Python免费学习笔记（深入）”；
组织文档内容：用 .rst 文件搭起逻辑骨架
index.rst 是入口，用 toctree 指令串联各章节：
.. toctree:: :maxdepth: 2 :caption: 目录 intro api/modules usage changelog
每个子文件（如 api/modules.rst）用 automodule 引入对应模块：
.. automodule:: mypackage.core :members: :undoc-members: :show-inheritance:
这种“模块即文档”的方式，让代码变更时只需更新 docstring，文档自然同步。
自动化构建与发布：集成进开发流程
把文档生成变成常规动作，避免遗忘或滞后：
- 加一条 Makefile 或 pyproject.toml 中的脚本命令：sphinx-build -b html docs/ docs/_build/html
- CI 中加入检查（如 GitHub Actions）：每次 push 后运行 sphinx-build -b linkcheck docs/ docs/_build/linkcheck 验证链接有效性
- 搭配 readthedocs.org 或 GitHub Pages 自动部署，源码一更新，文档站点就刷新
文档不是交付物，而是接口说明书。Sphinx 的价值，在于让这份说明书始终真实、可查、可执行。
