起因

用 Sphinx 写项目文档时，需求很快就超出“纯文字”：要画架构图、要写 PHP 项目的 API、要贴 Excel 参数表。Sphinx 的插件（extension）机制就是为这个准备的：pip 安装、conf.py 里登记，就能给文档系统加能力。这份清单收录几个常用的 sphinxcontrib 插件。

插件机制一页看懂

Sphinx 的所有扩展都在 conf.py 的 extensions 列表里登记，以 mermaid 为例三步走：

1
2
3
4

# 1. 安装：pip3 install sphinxcontrib-mermaid
# 2. conf.py 里登记：
extensions = ['sphinxcontrib.mermaid']
# 3. 文档里用对应指令/代码块写图源码，构建时渲染

其余插件同理，只是模块名与提供的指令不同（见各插件文档）。

插件清单

美人鱼图插件（Mermaid）

pip3 install sphinxcontrib-mermaid

插件网站：https://www.cnpython.com/pypi/sphinxcontrib-mermaid

Mermaid 是“图表即代码”：在文档里写文本描述（流程图、时序图、类图、甘特图），构建时渲染成图。优点是图跟着文档走、进版本库可 diff；不需要本地 Java 环境。

PHP插件

pip3 install sphinxcontrib-phpdomain

插件网站：https://www.cnpython.com/pypi/sphinxcontrib-phpdomain

Sphinx 的“domain（域）”是为某语言提供的对象指令与交叉引用体系（自带的 py domain 对应 Python）。phpdomain 补上了 PHP：php:class、php:function 等指令写 API，还能自动生成索引与链接。写 PHP 项目的 API 文档用它。

Excel 插件

pip3 install sphinxcontrib-excel

插件网站：https://www.cnpython.com/pypi/sphinxcontrib-excel

把 .xlsx 表格直接嵌入文档：参数表、寄存器表这类维护在 Excel 里的内容，不必手动转 Markdown 表格，文档里引用文件即可，改表后重新构建就同步。

UML插件（PlantUML）

pip3 install sphinxcontrib-plantuml

插件网站：https://www.cnpython.com/pypi/sphinxcontrib-plantuml

同样是“图表即代码”（UML 为主）。与 Mermaid 的关键差别：PlantUML 依赖本地 Java 运行环境（部分图还依赖 Graphviz），渲染能力更强、语法更老牌；Mermaid 纯前端/JS 渲染、上手更快。团队选型时按环境约束二选一即可。

怎么选

  • 画图：轻量/无 Java 环境 → mermaid；重度 UML/已有 PlantUML 资产 → plantuml；
  • 语言 API 文档：非 Python 语言找对应 domain 插件（如 PHP 用 phpdomain）；
  • 已有 Excel 维护的表格：excel 插件免搬运。

注意事项

  • 插件版本要和 Sphinx 版本匹配：Sphinx 大版本升级后老插件常见不兼容，升级前先看插件 changelog；
  • extensions 里登记的是模块名不是包名：如 sphinxcontrib.mermaid（安装的包叫 sphinxcontrib-mermaid），写错构建时找不到扩展；
  • plantuml 要先装 Java：CI 环境里别忘了这一步，本地能构建、CI 构建不过多半是缺运行时；
  • 构建报“unknown directive”：基本就是扩展没装/没登记，回 conf.py 的 extensions 列表检查。