在Python项目开发中，规范的项目文档能帮助其他开发者快速理解项目功能和使用方式，Sphinx就是一款专门用于生成Python项目文档的工具，支持将reStructuredText或Markdown格式的文档转换为静态HTML页面，还能自动提取代码中的注释生成API文档。
Sphinx环境安装
首先需要确保本地已经安装了Python环境，然后通过pip命令安装Sphinx，执行以下命令即可完成安装：
# 安装Sphinx pip install sphinx # 验证安装是否成功 sphinx-build --version
初始化Sphinx项目
安装完成后，我们可以为已有的Python项目初始化Sphinx文档目录，执行以下命令：
# 进入Python项目根目录 cd your_python_project # 初始化Sphinx文档目录，默认会生成docs文件夹 sphinx-quickstart docs
执行命令后会出现交互式配置选项，大部分可以直接使用默认配置，需要注意的两个选项：
- 是否分离源文件和构建目录，建议选择是，方便管理
- 项目名称和作者名称，填写实际的项目信息即可
编写文档内容
Sphinx默认使用reStructuredText格式编写文档，初始化完成后，docs/source目录下会有一个index.rst文件，这是文档的入口文件，我们可以修改这个文件添加内容：
# index.rst 示例内容 Welcome to MyProject's documentation! ===================================== .. toctree:: :maxdepth: 2 :caption: 目录: install usage api 简介 ---- 这是我的Python项目文档，包含安装说明、使用方法和API参考。
我们可以在同目录下创建install.rst、usage.rst等文件，编写对应模块的文档内容，然后在index.rst的toctree中添加对应的文件名（不需要后缀）即可关联到目录中。
配置Sphinx参数
文档的配置信息存放在docs/source/conf.py文件中，我们可以修改这个文件调整文档的基础设置：
# conf.py 部分配置示例
# 项目相关信息
project = 'MyProject'
copyright = '2024, 开发者名称'
author = '开发者名称'
# 文档主题设置，默认是alabaster，可更换为其他主题
html_theme = 'alabaster'
# 扩展配置，添加autodoc扩展可以自动提取代码注释生成API文档
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
]
如果需要使用其他主题，比如sphinx_rtd_theme，需要先安装对应主题包：pip install sphinx_rtd_theme，然后在conf.py中修改html_theme的值为sphinx_rtd_theme即可。
生成静态文档
完成文档编写和配置后，执行以下命令即可生成静态HTML文档：
# 进入docs目录 cd docs # 生成HTML文档，构建结果会存放在_build/html目录下 make html
生成完成后，打开docs/_build/html/index.html文件，就能看到完整的项目文档页面了。
自动生成API文档
如果需要在文档中展示Python代码的API说明，可以使用autodoc扩展，首先在conf.py中添加sphinx.ext.autodoc到extensions列表，然后编写rst文件引用代码模块：
# api.rst 示例内容 API参考 ======= .. automodule:: mymodule :members: :undoc-members: :show-inheritance:
其中mymodule是你的Python项目中的模块名，执行make html后，Sphinx会自动提取该模块中所有类、函数的注释，生成对应的API说明内容。
PythonSphinx文档生成reStructuredText修改时间：2026-07-12 03:21:21