Sphinx Python API 文档¶

一句话概述：Sphinx 是 Python 官方文档使用的生成器，能从代码注释自动提取 API 文档，支持输出 HTML/PDF/ePub 等多种格式。

核心知识点¶

概念	白话解释
Sphinx	Python 文档生成器 = 从代码注释生成文档
reStructuredText (RST)	标记语言 = Sphinx 的原生格式（比 Markdown 功能多）
MyST	Markdown 扩展 = 让 Sphinx 也能用 Markdown
autodoc	自动文档 = 从 Python docstring 自动生成 API 文档
toctree	目录树 = 组织文档结构
Read the Docs	托管平台 = 免费托管 Sphinx 文档

安装配置¶

pip install sphinx                                    # 安装 Sphinx
pip install sphinx-rtd-theme                           # 安装 Read the Docs 主题
pip install myst-parser                               # 安装 MyST（用 Markdown 写文档）

# 快速初始化
mkdir docs && cd docs                                 # 创建文档目录
sphinx-quickstart                                     # 交互式初始化
# 输入项目名、作者名，其他默认即可

配置文件 conf.py¶

# docs/conf.py

project = '我的项目'                                    # 项目名
author = '彭文强'                                       # 作者
release = '1.0.0'                                     # 版本号

# 扩展
extensions = [
    'sphinx.ext.autodoc',                              # 自动从 docstring 生成文档
    'sphinx.ext.napoleon',                             # 支持 Google/NumPy 风格注释
    'sphinx.ext.viewcode',                             # 在文档中链接源码
    'sphinx.ext.intersphinx',                          # 跨项目引用
    'myst_parser',                                     # 支持 Markdown
]

# 支持 Markdown 文件
source_suffix = {
    '.rst': 'restructuredtext',                        # RST 格式
    '.md': 'markdown',                                 # Markdown 格式
}

# 主题
html_theme = 'sphinx_rtd_theme'                        # Read the Docs 主题

# autodoc 配置
autodoc_member_order = 'bysource'                      # 按源码顺序排列
autodoc_typehints = 'description'                      # 类型注解放在描述中

写 Python Docstring¶

# src/my_module.py

def calculate_diversity(abundance_table, method="shannon"):
    """计算微生物多样性指数。

    从物种丰度表计算 Alpha 多样性。

    Args:
        abundance_table (pd.DataFrame): 物种丰度表，行=样本，列=物种。
        method (str): 多样性指数方法，可选 "shannon"、"simpson"。
            默认为 "shannon"。

    Returns:
        pd.Series: 每个样本的多样性指数。

    Raises:
        ValueError: 丰度表包含负值时抛出。

    Example:
        >>> import pandas as pd
        >>> df = pd.DataFrame({'sp1': [10, 20], 'sp2': [30, 40]})
        >>> calculate_diversity(df, method="shannon")
        0    0.811
        1    0.811
        dtype: float64
    """
    if (abundance_table < 0).any().any():               # 检查负值
        raise ValueError("丰度表不能包含负值")
    # ... 计算逻辑

自动生成 API 文档¶

.. docs/api.rst

API 参考
========

my_module 模块
--------------

.. automodule:: my_module
   :members:
   :undoc-members:
   :show-inheritance:

# 自动扫描代码生成 RST 文件
sphinx-apidoc -o docs/api src/                        # 扫描 src/ 生成 API 文档

# 构建 HTML
cd docs
make html                                             # 构建（输出到 _build/html/）

# 构建 PDF（需要 LaTeX）
make latexpdf                                         # 生成 PDF

常见报错¶

报错	原因	解决
`No module named 'xxx'`	autodoc 找不到模块	在 conf.py 中添加 `sys.path.insert(0, '../src')`
`Unknown directive 'automodule'`	没启用 autodoc	`extensions` 中加 `'sphinx.ext.autodoc'`
`toctree contains reference to nonexisting document`	引用了不存在的文件	检查 toctree 中的文件名
`WARNING: duplicate object description`	重复定义	检查是否重复 automodule

速查表¶

# 常用命令
sphinx-quickstart                                     # 初始化项目
sphinx-apidoc -o docs/api src/                        # 自动生成 API 文档
make html                                             # 构建 HTML
make latexpdf                                         # 构建 PDF

# 主要扩展
# autodoc    → 从 docstring 生成文档
# napoleon   → 支持 Google/NumPy docstring 风格
# viewcode   → 文档中显示源码链接
# myst_parser → 用 Markdown 写 Sphinx 文档
# intersphinx → 跨项目交叉引用

# Docstring 风格选择
# Google 风格 → Args: / Returns: / Raises:（推荐）
# NumPy 风格 → Parameters / Returns（科学计算常用）