文档站点生成器 - Sphinx

简介Sphinx 是一个高度可扩展、功能丰富的文档生成工具最初为 Python 官方文档开发现已成为技术文档领域的事实标准。它支持从 reStructuredText 或 Markdown 源文件生成多种输出格式HTML、PDF、ePub、LaTeX 等。核心特点特性说明多格式输出一份源码同时生成 HTML、PDF、EPUB、LaTeX 等reStructuredText语义化标记语言支持复杂文档结构MyST-Parser 支持原生兼容 Markdown降低迁移成本自动 API 文档从 Python 代码注释自动生成文档autodoc交叉引用系统强大的标签、索引、引用和搜索功能国际化i18n完整的文档翻译和多语言支持扩展生态数百个扩展插件涵盖图表、代码、主题等典型应用场景Python 官方文档docs.python.org大型开源项目NumPy、Pandas、Django、Flask、scikit-learn企业级技术文档需要版本控制、多格式输出、复杂索引学术论文与书籍LaTeX/PDF 输出质量专业快速开始1. 安装# 基础安装 pip install sphinx # 推荐组合含 Markdown 支持、常用主题、自动文档 pip install sphinx myst-parser sphinx-rtd-theme sphinx-autodoc-typehints2. 初始化项目mkdir my-docs cd my-docs sphinx-quickstart docs交互式配置向导会询问项目名称、作者、版本是否分离源码和构建目录推荐y是否创建 Makefile推荐y生成的目录结构docs/ ├── build/ # 构建输出目录 ├── make.bat # Windows 构建脚本 ├── Makefile # Unix 构建脚本 ├── source/ # 文档源文件 │ ├── _static/ # 静态资源 │ ├── _templates/ # 自定义模板 │ ├── conf.py # 核心配置文件Python 格式 │ ├── index.rst # 主文档入口 │ └── ... # 其他 .rst/.md 文件 └── ...3. 配置文件source/conf.py# 项目信息 project 我的项目文档 copyright 2026, 作者名 author 作者名 release 1.0.0 # 扩展模块 extensions [ myst_parser, # 支持 Markdown sphinx.ext.autodoc, # 自动生成 Python API 文档 sphinx.ext.viewcode, # 源码链接 sphinx.ext.napoleon, # 支持 Google/NumPy 风格 docstrings sphinx.ext.intersphinx,# 跨项目链接如链接到 Python 官方文档 sphinx.ext.todo, # TODO 标记 sphinx.ext.mathjax, # LaTeX 数学公式 ] # 源文件后缀 source_suffix { .rst: restructuredtext, .md: markdown, } # 主题设置Read the Docs 主题 html_theme sphinx_rtd_theme # 静态文件路径 html_static_path [_static] # 自定义 CSS html_css_files [custom.css] # 交叉引用映射链接到其他 Sphinx 文档 intersphinx_mapping { python: (https://docs.python.org/3, None), numpy: (https://numpy.org/doc/stable/, None), } # 自动文档设置 autodoc_member_order bysource autodoc_typehints description4. 编写文档reStructuredText 示例index.rst.. 我的项目文档 documentation master file 欢迎文档! .. toctree:: :maxdepth: 2 :caption: 目录: quickstart api advanced 索引与表格 * :ref:genindex * :ref:modindex * :ref:search .. note:: 这是一个提示框reStructuredText 的指令语法。Markdown 示例quickstart.md# 快速开始 {toctree} :hidden: install config安装pip install my-package基本用法参见 {ref}api-reference或 {doc}api。这是一个警告框使用 MyST 语法。### 5. 自动生成 API 文档 这是 Sphinx 的核心优势。假设有以下 Python 代码 python # mypackage/core.py def process_data(data: list[dict], threshold: float 0.5) - dict: 处理数据并返回统计结果。 :param data: 输入数据列表每个元素为字典 :param threshold: 过滤阈值默认为 0.5 :return: 包含 mean、std、count 的字典 :raises ValueError: 当数据为空时抛出 示例:: result process_data([{val: 1.0}, {val: 2.0}]) print(result[count]) 2 if not data: raise ValueError(数据不能为空) # ... 实现逻辑 return {mean: 1.5, std: 0.5, count: len(data)}在文档中自动引用.. automodule:: mypackage.core :members: :undoc-members: :show-inheritance: :special-members: __init__或 Markdown 版本{automodule} mypackage.core :members: :undoc-members: :show-inheritance:### 6. 构建与预览 bash # 进入文档目录 cd docs # 构建 HTML输出到 build/html make html # 启动本地服务器预览 python -m http.server 8000 -d build/html # 构建 PDF需安装 LaTeX make latexpdf # 清理构建缓存 make clean部署方案GitHub Pages GitHub Actions创建.github/workflows/sphinx.ymlname: Sphinx Documentation on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install sphinx myst-parser sphinx-rtd-theme pip install -e . # 安装你的包以生成 API 文档 - name: Build HTML run: | cd docs make html - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pagesv3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/build/htmlRead the Docs推荐原生支持导入 GitHub 仓库到 readthedocs.org创建.readthedocs.yaml配置文件version: 2 build: os: ubuntu-22.04 tools: python: 3.11 python: install: - method: pip path: . - requirements: docs/requirements.txt sphinx: configuration: docs/source/conf.py formats: - htmlzip - pdf - epub常用扩展推荐扩展名功能myst-parserMarkdown 支持sphinx-autodocPython API 自动生成sphinx-autodoc-typehints类型提示自动文档sphinx-copybutton代码块复制按钮sphinx-design卡片、标签页、网格等 UI 组件sphinxcontrib-mermaidMermaid 流程图sphinx-tabs标签页内容sphinx-last-updated-by-git显示最后更新时间