部署 Sphinx 文档
Python 文档生成器，reStructuredText，HTML 输出部署到任何主机。
平台进阶
为什么
Sphinx 是 Python 文档标准（Python 本身、Django、NumPy 使用）。擅长 API 文档，支持 autodoc、交叉引用和多格式输出（HTML、PDF、ePub）。
平台即服务采用率 2024 年增长 24%，团队从虚拟机管理转向 git push 部署。the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research)，PaaS 层捕获了大多数新工作负载。
何时使用
Python 库文档、API 参考和技术书籍用 Sphinx。Web 应用文档避免 — MkDocs/Docusaurus 更简单。
如何做
1. 构建 — sphinx-build -b html docs/ build/html
2. 部署 — 上传 build/html/ 到任何静态主机
3. 配置 — conf.py 配主题、扩展、autodoc
4. Autodoc — sphinx-apidoc 从 docstring 生成 RST
5. 主题 — furo 或 sphinx-rtd-theme 现代外观
示例
# conf.py — Sphinx 配置
project = "My Project"
extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
html_theme = "furo"
# 构建并部署
sphinx-build -b html docs/ build/html
npx wrangler pages deploy build/html
# 从 docstring 生成 API 文档
sphinx-apidoc -o docs/ src/mypackage/
常见问题
- ⚠Autodoc 找不到模块 — conf.py 未设 sys.path，加包根
- ⚠RST 语法错误 — 不同于 Markdown，用 .. directive:: 语法
- ⚠环境间配置漂移 — 使用基础设施即代码（Terraform/Pulumi）保持 dev/staging/prod 一致
最佳实践
- ✓用 furo 主题 — 现代、响应式、活跃维护的 Sphinx 主题
- ✓启用 napoleon 扩展支持 Google/NumPy 风格 docstring — 更清晰 Python 文档
- ✓设置健康检查和优雅关闭 — 处理 SIGTERM 以在退出前排空进行中的请求