去年年中我接手一个内部 SDK 的文档重构仓库里散着三十多个 Markdown 文件README、Wiki、博客各写一套版本迭代之后文档和代码已经明显对不上了。纠结了 MkDocs、VuePress、GitBook 一圈之后我最终选了 Sphinx。说实话刚开始上手那周确实有点劝退——reStructuredText 的语法和 Markdown 差别很大toctree 的理解成本也比想象中高。但坚持用了两个月这套工具成了我在项目里最不后悔的技术选型之一。这套流程特别适合三种人一是要给 Python 项目、嵌入式项目或算法项目写完整文档的开发者二是团队里文档散乱、需要从零搭建统一文档站点的技术负责人三是已经被 MkDocs 的 Markdown 扩展限制折磨得够呛、想换一条路的老手。下面直接进入正题。1. 为什么是 Sphinx一个文档维护者的选型思考1.1 Sphinx 到底解决了什么问题Sphinx 是基于 Python 的文档生成工具最初是为了生成 Python 官方文档而设计的。它用纯文本格式主要是 reStructuredText也可以搭配 MyST 解析器写 Markdown作为源文件然后输出成 HTML、PDF、EPUB、man page 等多种格式。我之所以在重构中选它核心原因就一个它能同时解决“文档结构”和“文档与代码一致性”两个问题。Markdown 散落在多个仓库里的时候最大的问题不是写而是索引。你根本不知道哪个文件是旧的哪份说明还能用别人提问时你也只能凭着记忆到处翻。Sphinx 用 toctree 把文档页组织成一个有层级、有顺序的站点架构导航、目录、上一页下一页全部自动生成。文档一旦上了这个框架就变成了一个真正可以被浏览和被检索的“站点”而不是一堆孤立的 md 文件。更重要的是 autodoc 扩展。它可以直接读取 Python 模块、类和函数的 docstring自动生成 API 参考文档。这意味着你只要把 docstring 写得规范文档里就可以少写一大半手工内容而且永远不会出现“函数签名改了文档没改”的尴尬。1.2 与 MkDocs、Docusaurus 的选择差异很多人在选型时会拿 Sphinx 和 MkDocs、Docusaurus 对比。我的看法是没有绝对的好坏只有匹配不匹配。维度SphinxMkDocsDocusaurus默认源格式reStructuredText / MarkdownMarkdownMDXReact 组件语法API 文档自动生成原生 autodoc强需插件体验依赖主题有限通常要自己写组件排版与 PDF 输出LaTeX 管道适合正式出版物弱多依赖浏览器打印弱通常是 web 优先学习曲线中等偏上低中高涉及 React 生态典型使用者Python 项目、学术文档、RTOS 文档轻量项目、内部工具前端开源项目、组件库如果你要维护的是 Python 库、底层中间件这类强 API 属性的项目Sphinx 的 autodoc 交叉引用组合几乎是无敌的。如果你只是需要快速上线一个静态技术博客或小工具说明MkDocs 更省事。Docusaurus 最适合前端组件库因为它本身就能嵌 React 交互组件这是 Sphinx 很难做到的优势。1.3 什么场景不适合 Sphinx我也得诚实地提一下反例。团队里完全没有人熟悉 Python且业务文档以交互式图表为主Sphinx 会成为一个负担。尤其是 LaTeX 出 PDF 这条管线第一次配置字体和宏包真的能折腾掉一整个工作日。另外如果你的“文档”其实就是几十页的团队 Wiki而且要频繁多人编辑Sphinx 从源码构建再提交部署的流程就太重了。那种场景直接用带编辑器的在线 Wiki 或 MkDocs 的托管方案更合理。选型时先把“文档的量级”和“团队的技术栈”放在前面比追热点重要得多。2. 环境准备与初始化先把骨架搭起来2.1 Python 环境与虚拟环境Sphinx 是纯 Python 工具装它必须有 Python 环境。建议直接上 Python 3.10当前主流的 Sphinx 8.x 在 3.11、3.12 上运行都很稳。我不太建议直接把 Sphinx 装到系统 Python 里尤其是开发机版本冲突和权限问题会烦死你。每个文档项目单独建一个虚拟环境成本很低收益很高。python -m venv .venv # Windows 用 .venv\Scripts\activatemacOS/Linux 用下面这行 source .venv/bin/activate pip install sphinx为了后面少折腾我习惯把常用依赖一次性装好pip install sphinx furo sphinx-rtd-theme myst-parser sphinx-design sphinx-copybutton这里我故意把 furo 和 sphinx-rtd-theme 都装上因为不同项目审美不一样换主题只是改一行配置的事没必要后来再补装。myst-parser 是为了让团队里习惯 Markdown 的同事也能写源文件sphinx-design 和 sphinx-copybutton 后面讲主题时会用到。2.2 sphinx-quickstart 初始化Sphinx 提供了交互式初始化命令在源文件目录下执行sphinx-quickstart过程中会问你几个问题其中有两个值得认真回答Separate source and build directories是否分离源文件目录和构建目录选 yes。我建议所有正规项目都选 yes源文件归源文件构建产物随时可以删掉重建不会污染仓库。Project language填zh_CN。这个设置会影响界面文案和搜索分词中文项目一定要填对。交互完成后你会得到一个典型的 Sphinx 项目结构. ├── make.bat ├── Makefile ├── source │ ├── _static │ ├── _templates │ ├── conf.py │ ├── index.rst │ └── ... └── build顺手验证一下在项目根目录执行make htmlWindows 是make.bat html浏览器打开build/html/index.html看到默认的 alabaster 主题页面骨架就算立住了。2.3 conf.py 里第一次就要改好的配置conf.py 是整个 Sphinx 构建的枢纽我每次新建项目都会在一开始就把下面这几项改掉而不是等项目写了一半再补project MySDK author Your Name release 1.0.0 language zh_CN extensions [ sphinx.ext.autodoc, sphinx.ext.autosummary, sphinx.ext.intersphinx, sphinx.ext.napoleon, sphinx.ext.viewcode, sphinx.ext.mathjax, myst_parser, sphinx_design, sphinx_copybutton, ] html_theme furo html_title MySDK 技术文档这几个扩展我会在后续章节详细说这里先提一下autosummary和viewcode一个是在 API 页面生成摘要索引一个是给文档页附上“查看源代码”的链接对技术类文档来说都属于用了就回不去的体验。3. 写作核心reStructuredText 和 toctree 的正确打开方式3.1 标题结构与 reST 基础语法Sphinx 的默认源格式是 reStructuredTextreST它和 Markdown 最直观的区别在于标题是用符号下划线标记的而不是用#号。一级标题 二级标题 --------- 三级标题 ~~~~~~~~~这里有个很坑的细节同一层级的标题必须使用同一个下划线符号而且符号顺序就是层级顺序。比如是二级那么全篇的二级标题都必须用中途换成一个新的符号会让 Sphinx 直接调整层级你的目录结构瞬间乱掉。我团队内部定的规矩是一级、-二级、~三级、^四级写新文档时先把这个规则贴到文件头部省了很多返工。普通段落和 Markdown 没什么区别空行分段即可。斜体和加粗分别是*斜体*和**加粗**。3.2 代码块、提示框和表格技术文档里的代码块是最常用的元素之一。reST 里的标准写法是.. code-block:: python :caption: 一个示例 def add(a, b): return a b注意.. code-block:: python后面的内容必须整体缩进四格或与指令右对齐这是 reST 的著名“敏感缩进”。我就见过不少同事在这里被缩进折腾了半天最后发现只是少了一个空格。提示框也是 reST 的亮点之一写注意事项比 Markdown 里手动加粗引用块体面得多.. note:: 这是一个普通提示。 .. warning:: 这里是比较重要的警告会以醒目样式显示。sphinx-design 扩展还会带来.. grid::、.. card::这类富 UI 元素但那些属于锦上添花。表格方面reST 原生网格表格太折磨人我建议直接使用list-table指令.. list-table:: :header-rows: 1 * - 参数名 - 类型 - 说明 * - timeout - int - 超时秒数默认 30这种写法和手工维护 Markdown 表格相比没那么直观但它胜在结构稳定而且列数多了之后不会把编辑器弄成乱码。3.3 toctree文档的组织核心这是 Sphinx 和普通静态站点生成器最不一样的地方。toctree 不是入口目录而是文档页的“编排表”。它决定哪些页面出现在导航里、以什么顺序出现、层级如何嵌套。根目录的 index.rst 里通常会写.. toctree:: :maxdepth: 2 :caption: 用户指南 intro install usage/index每个子目录也可以有自己的 index.rst 和 toctree形成嵌套导航。一个常见的工程组织方式是这样source/ ├── index.rst ├── intro.rst ├── install.rst └── usage/ ├── index.rst ├── cli.rst └── api.rstusage/index.rst里再写一个 toctree 指向cli和apiSphinx 就会自动把它们挂到总目录下面。这个机制很容易理解但容易被忽略在 Sphinx 里页面之间的导航关系完全由 toctree 控制而不是由文件目录决定。文件在磁盘上怎么摆都行但如果不被任何 toctree 引用构建时就会报 “document isnt included in any toctree” 的警告。如果你的文档页很多、不想一个个手写文件名也可以直接用 glob 语法.. toctree:: :glob: usage/*不过我不太推荐大规模使用 glob因为它会让页面的排序失去显式控制尤其是某个目录下以后混入了草稿文件你完全不知道它什么时候就悄悄上线了。3.4 交叉引用文档内部的“超链接”体系Sphinx 真正的护城河是交叉引用。它可以给文档中任意位置打上标签然后从任何页面跳转过去而且链接目标变更后生成的链接地址会自动更新。先在目标章节打标签.. _install-macos: macOS 安装 ----------然后其他页面可以直接引用详细的 macOS 安装流程见 :ref:install-macos。除了自定义标签Sphinx 还支持直接引用文档页和 API 对象:doc:/install :func:os.path.join :class:MyPackage.Client :meth:MyPackage.Client.connect这就是为什么我前面坚持加了 intersphinx 扩展。配置好官方 Python 文档映射之后连 Python 标准库的链接都不用自己拼 URLintersphinx_mapping { python: (https://docs.python.org/3, None), }多个 Sphinx 项目之间也可以配置 intersphinx这意味着 team A 的文档可以直接:class:引用 team B 的类并且自动带上正确的链接。对于多模块的团队这个能力是很多纯 Markdown 方案完全无法替代的。4. 自动化 API 文档autodoc 才是 Sphinx 的杀手锏4.1 扩展配置与 docstring 风格前面说 autodoc 能读取 docstring 生成 API 文档关键在于搭配 napoleon 扩展。它让 Sphinx 能解析 Google 风格和 NumPy 风格的 docstring而不仅仅是 reST 格式。我团队的标准是这样def connect(host: str, port: int 8080) - None: 建立到服务端的连接。 Args: host: 服务器地址。 port: 端口号默认 8080。 Returns: 无返回值。 Raises: ConnectionError: 连接失败时抛出。 这种 docstring 比一堆散落的注释要严肃得多而且 PyCharm 和 VS Code 都能识别。autodoc 配置上我习惯在 conf.py 里加这几项autodoc_member_order bysource autodoc_typehints description autodoc_mock_imports []autodoc_member_order bysource让成员按源码出现顺序排列而不是按字母序读起来更自然autodoc_typehints description把类型注解放到参数描述里而不是生成在签名前界面更干净。4.2 在页面里使用 autodoc 指令API 参考页面的 rst 文件可以写得很短因为它只是“容器”真正的内容来自源码里的 docstring。举个典型例子在api.rst里API 参考 .. automodule:: mypackage.client :members: :undoc-members: :show-inheritance:构建时 Sphinx 会导入mypackage.client模块读取模块内所有公开类和函数的 docstring自动生成带签名、带参数说明、带继承关系的完整页面。如果不想要一整个模块只想挑个别对象可以用autoclass和autofunction.. autoclass:: mypackage.client.Client :members: :special-members: __init__ .. autofunction:: mypackage.client.connect这里有一个很实用的细节:members:会列出所有公开成员:undoc-members:会把没有 docstring 的成员也列出来方便你发现“谁还没写注释”。这种从构建层反推代码注释质量的能力是我在其他文档工具里很少见到的。4.3 autosummary让 API 文档自成索引API 一多一个页面里堆几百个函数显然不现实。autosummary 就是干这个的它在页面上生成一个摘要表格每一项都是一个链接指向一个单独生成的详细页面。.. autosummary:: :toctree: generated mypackage.client.Client mypackage.client.connect mypackage.client.disconnect:toctree: generated会让 Sphinx 在generated/子目录里为每个对象生成独立页面点击表格中的名称就能跳转过去。这种组织方式很适合 SDK 这种 API 量大、每个类的方法又多又有细节的项目。效果就是你的文档站有了“API 索引页 每个对象详情页”的标准结构几乎不需要手工维护。4.4 autodoc 的限制和替代方案autodoc 并不是万能的它最大的限制在于构建时必须把 Python 模块导入进来。一旦某个模块在 import 阶段连接数据库、读环境变量或者启动线程池构建就会卡住甚至直接失败。这时候有两个方向一是用autodoc_mock_imports屏蔽掉那批有副作用的第三方依赖autodoc_mock_imports [numpy, pandas]二是换用 autoapi。它不执行 import而是直接解析源代码的 AST 树来生成文档对导入副作用免疫。代价是某些动态生成的类和方法可能会漏掉。我的实践经验是优先 autodoc代码的 import 副作用实在清不掉再上 autoapi。另外第一次在 autodoc 里引用自定义模块时大概率会遇到 ModuleNotFoundError。这不是 autodoc 有问题而是 Sphinx 构建时的 sys.path 并没有指向你的项目根目录。在 conf.py 里加上import sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent.parent.parent))路径层级取决于 conf.py 所在的位置我这里是 docs/source/conf.py所以上溯三层到项目根目录。这个细节忘了autodoc 就只能“望包兴叹”。5. 主题与多格式输出让文档在不同场景下都好用5.1 主题选型先用起来再慢慢调Sphinx 默认的 alabaster 主题不是不能用只是和现代文档站点的观感差距有点大。我目前用得最多的是 Furo 和 Read the DocsRTD主题。Furo视觉现代窄栏阅读体验好适合产品文档和项目首页合一。RTD 主题经典侧边栏信息密度高适合大型 API 文档和教程体系。Furo 的配置非常简单html_theme furo html_title MySDK 技术文档RTD 主题则还可以加版本选择器和语言切换器适合多版本文档场景。选主题时先别看花哨的 demo盯住两个指标就行侧边栏能不能承载你要的目录深度正文区在代码块很多的时候是否还阅读友好。5.2 扩展组合copybutton、design 与导航体验纯静态页面很容易给人一种“还没做完”的感觉几个扩展能快速改善体验sphinx_copybutton给所有代码块自动加“复制”按钮读者不用再像以前那样手动框选代码。sphinx_design提供卡片、网格、折叠块等 UI 组件适合做快速上手板块。sphinxext.opengraph让文档链接分享到微信、Slack 时能显示标题和卡片图。sphinx_sitemap生成 sitemap.xml对做官网子站、要 SEO 的项目友好。这些扩展大多只需在 conf.py 的 extensions 里加一行然后在 rst 里写对应指令。我建议不要一次上太多先加 copybutton 和 design等整体结构稳定了再补 SEO 相关的能力。扩展这玩意儿三分之一的人是“全都想装”三分之一的人“装了忘了加进 extensions 列表”真正对你站点有用的通常只有那么三五个。5.3 多格式输出HTML、PDF、EPUB 与 man 手册Sphinx 本身就是多格式输出的这也是它对比 MkDocs 的一个显著优势。同一套源文件你可以make html输出在线文档make epub输出电子书做离线阅读非常方便make man输出 Linux man page适合命令行工具make latexpdf输出排版规整的 PDF但这里我要给个现实建议不要一上来就追求 PDF 管线。PDF 依赖一套完整的 LaTeX 环境在你的机器上配置成功的路径不一定能平移到同事机器上。如果只是内部审阅完全可以直接用浏览器打印 HTML 页面成 PDF省心得多。如果产品确实需要对外发布正式排版 PDF再把 LaTeX 环境放进 Docker 镜像里一套配置跑到底而不是在每个人本地去折腾。5.4 中文 PDF 的字体配置终于说到中文 PDF 了这是 Sphinx 中文用户最常踩的大坑。默认的 PDF 管线用的是 pdflatex它对中文字体支持基本等于零不配置直接构建出来就是一堆方块。标准做法是切换 LaTeX 引擎为 xelatex并在 preamble 里指定中文 CJK 字体latex_engine xelatex latex_elements { preamble: r \usepackage{xeCJK} \setCJKmainfont{Noto Serif CJK SC} \setCJKsansfont{Noto Sans CJK SC} \setCJKmonofont{Noto Sans Mono CJK SC} , }Linux 系统上先检查有没有中文字体fc-list :langzh如果没有输出就装字体包Debian/Ubuntu 上是fonts-noto-cjk。macOS 上则可以把字体名换成PingFang SCWindows 上是Microsoft YaHei。这步属于典型的“文档两句话实操两小时”环节建议把字体检查放在 PDF 构建脚本里遇到缺字体直接报错并提示安装不要等 PDF 生成完才发现是全方块。6. 发布部署与版本管理从本地文档到在线站点6.1 Read the Docs 的接入如果不想维护服务器和构建流程Read the DocsRTD是接入 Sphinx 文档最省心的方案。它支持直接从 GitHub、GitLab 或 Bitbucket 拉取代码自动执行 Sphinx 构建然后托管到它的域名下还能免费支持多版本。新版 RTD 使用.readthedocs.yaml配置构建环境在仓库根目录放一个version: 2 build: os: ubuntu-22.04 tools: python: 3.11 sphinx: configuration: docs/source/conf.py fail_on_warning: false python: install: - requirements: docs/requirements.txt注意fail_on_warning我建议一开始关掉。Sphinx 对细节非常较真随便一个 reST 语法警告就会导致构建失败而新手阶段警告是清理不完的。先让它能成功上线后续再在 CI 里逐步收紧。RTD 的版本管理也很舒服默认分支对应latestpublish 一个 git tag 就会自动出现在版本列表里你可以把某个 tag 设为stable。这样用户永远能看到“最新开发版”和“稳定版”两套文档体验一下子就正规了。6.2 GitHub Actions 构建 GitHub Pages如果不依赖 RTD或者想用 GitHub Pages 做对外站点建议用 GitHub Actions 自动构建。我的 workflow 如下name: docs on: push: branches: [main] workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install -r docs/requirements.txt - run: sphinx-build -M html docs/source docs/build - uses: actions/upload-pages-artifactv3 with: path: docs/build/html deploy: environment: name: github-pages runs-on: ubuntu-latest needs: build steps: - id: deployment uses: actions/deploy-pagesv4这个方案的好处是零成本、构件可追溯每次 push 到 main 分支就自动重新生成站点。缺点是没有 RTD 那种自动多版本列表想要多版本得自己用 sphinx-multiversion 之类的插件或者按版本目录去生成。6.3 多版本文档管理多版本管理的本质很简单每个线上版本对应一份独立的 HTML 产物访问入口切换版本目录。具体做法有两种用 sphinx-multiversion 插件在同一个构建里 checkout 多个 tag 并分别构建。在 CI 里循环执行git checkout构建后把产物统一放进versions/目录。这里有一个关键心得不管用哪种方式都务必在 requirements.txt 里锁定所有扩展版本否则仓库里的老 tag 在新版本 Sphinx 下可能构建失败。真实教训某个老版本用了废弃的 reST 语法新 Sphinx 直接升级为 error历史版本文档一夜之间全挂。锁版本这个动作真的要在项目一开始就养成本能。7. 踩坑与心得几个差点劝退我的问题7.1 autodoc 导入失败构建直接崩症状很典型构建到 API 页面时Sphinx 报 ModuleNotFoundError 或导入副作用报错堆栈却指向你的业务代码而不是任何 rst 文件。第一次遇到的人会以为文档工程坏了其实只是 autodoc 在执行“为了读注释而导入模块”这步时把你的业务代码真的跑了一遍。排查思路是分两步。先在命令行手动执行那个模块的导入确认业务代码在 import 阶段有没有副作用然后确认 conf.py 里的 sys.path 是否包含源码路径。如果业务代码确实不能免导入执行就优先用autodoc_mock_imports屏蔽第三方依赖或者把 import 阶段产生副作用的语句挪到函数内部。还有一个技巧是if TYPE_CHECKING:条件导入既能满足类型检查器又能避免运行时导入。7.2 改了内容却不生效缓存背锅这是 Sphinx 增量构建带来的经典问题。你改了 index.rst刷新浏览器发现什么都没变第一反应是代码写错了其实很可能是构建缓存没更新。Sphinx 的增量构建机制有时会漏掉对主题文件、conf.py 变更的感知尤其是你刚刚安装了一个新主题或修改了 html_theme_options。我处理这类问题的标准操作顺序是先强制刷新浏览器再make clean make html最后检查是不是有多个 conf.py 或 build 目录残留在项目里。八成问题到最后都是缓存或路径指错了。7.3 Windows 下的中文编码问题开发环境是 Windows 的团队大概率会遇到控制台报UnicodeDecodeError。原因很简单Sphinx 源文件默认要求 UTF-8 编码而 Windows 控制台在部分地区默认不是 UTF-8。解决办法有三个按稳定程度排序所有 rst、py、conf.py 文件强制存为 UTF-8编辑器统一设置。在 Windows 环境变量里设置PYTHONUTF81让 Python 运行时强制使用 UTF-8。构建命令前执行chcp 65001切换控制台代码页。这个问题看起来小但足够让一个团队在项目初期消耗一整天的耐心。建议在 README 里把编码要求直接写清楚。7.4 莫名其妙的 orphan 警告每次构建到最后总会看到几个 “document isnt included in any toctree” 的黄色警告。新手往往会急着加:orphan:标记把警告压掉我强烈不建议这么做。:orphan:相当于告诉 Sphinx“这个页面确实没有导航入口别管我了”但一个正常文档站里不应该有大量页面是无入口的。正确做法是回到 toctree 配置里把遗漏的页面挂到对应章节下。:orphan:只适合应对少数“仅供下载或引用不进入导航”的特殊页面比如许可协议全文、内部设计草稿。无脑压警告最后的结果就是一批页面在网上蒸发读者靠搜索才知道它们存在。最后再分享一点个人体会。Sphinx 的上手曲线确实是有些陡峭reST 的缩进规则、toctree 的编排逻辑、autodoc 的导入机制每一关都能劝退一批人。但你要是把文档写代码这件事想明白了会发现它其实是把“文档”从一个结果变成了一套工程系统写 docstring 是编码规范、rst 源文件是产品源码、Sphinx 构建是 CI 流程、站点部署是发布过程。文档一旦进入这套流程质量就不再依赖某个人的自觉性而是被工具链兜住了。这大概就是它和普通 Markdown“随手写写”之间最大的差别。如果你正在犹豫要不要换成 Sphinx我的建议是先拿一个真正的项目跑通make html不急着折腾主题和 PDF。先把源码结构、toctree、autodoc 和交叉引用这四件事跑顺你就已经超过八成用它的人了。剩下的主题、扩展、多版本都是遇到一个需求再逐步加一个能力的路线完全不用一开始就追求完美配置。