一、什么是 Sphinx？

发现了吗？你辛辛苦苦写了一个超厉害的 Python 项目，满心欢喜地准备分享给全世界。但别人拿到你的代码，却一脸懵，不知道从哪儿下手。这时候，一份清晰易懂的文档就像一盏明灯，照亮他们探索你代码世界的道路。而 Sphinx 就是帮你打造这盏明灯的神奇工具！

Sphinx 是一个专门用于生成 Python 项目文档的工具，它功能强大，能把你写在代码里的注释，按照一定的规则转化成漂亮的 HTML、PDF 等格式的文档。有了它，你的项目瞬间高大上起来，不仅别人用着方便，自己维护起来也轻松很多。

二、安装 Sphinx

开始之前，确保你已经安装了 Python 和 pip。打开命令行，输入下面的命令，就像给电脑下达一个 “安装 Sphinx” 的指令：

pip install sphinx sphinx_rtd_theme

电脑就会像勤劳的小蜜蜂一样，自动去把 Sphinx 安装好。安装完成后，我们就可以开始搭建文档项目啦！注意：安装的东西有点多，所以要设置好靠谱的国内pip安装源，例如阿里源或清华源等等。

三、创建新项目

mkdir mydocs
cd mydocs
sphinx-quickstart

这时候，程序会开始问你一堆问题。别害怕，跟着下面的步骤来回答：

1. 项目路径：直接回车，使用默认路径，也就是当前目录。
2. 项目名称：输入你项目的名字，比如 “My Project”。
3. 作者名字：写上你的大名，让大家知道这么厉害的文档是谁写的。
4. 项目版本：比如 “1.0”，代表你的项目版本号。
5. 选择语言：zh_CN

回答完这些问题，Sphinx 就会在你的项目目录里创建一个文档项目（注意：不是已经生成了文档，而是构建了一个用来自动制作文档的项目，在你的项目目录中生成了一个source目录），就像给你的项目盖了一栋漂亮的文档大楼，里面有各种房间（文件和目录）等着我们去布置。

总之，按提示完成配置：

• 项目名称：My Project

• 作者：Your Name

• 版本：1.0

• 语言：zh_CN（中文文档）

四、项目结构

mydocs/
├── build/          # 生成的文档
├── source/
│   ├── conf.py     # 配置文件
│   ├── index.rst   # 文档入口
│   └── _static/    # 静态文件

五、编写文档内容

编辑 index.rst

欢迎阅读 My Project 文档！
================================

目录结构：

.. toctree::
   :maxdepth: 2
   :caption: 内容目录:

   chapter1
   chapter2

创建章节文件

touch source/chapter1.rst
touch source/chapter2.rst

 章节文件基本按照如下语法示例：

标题
====

小节
----

段落文本，*斜体*，**粗体**

代码块：

.. code-block:: python

    def hello():
        print("Hello Sphinx!")

列表：
- 项目1
- 项目2

表格：

+---------+---------+
| Header1 | Header2 |
+=========+=========+
| Cell1   | Cell2   |
+---------+---------+

 六、构建文档

make html  # 生成HTML
# 其他格式
make latexpdf   # PDF
make epub       # ePub

 七、自定义配置（必做）

修改 conf.py：

import os
import sys
sys.path.insert(0, os.path.abspath('<此处项目源码目录路径>'))

html_theme = 'sphinx_rtd_theme'  # 使用 ReadTheDocs 主题
extensions = ['sphinx.ext.autodoc']  # 启用自动文档生成

八、高级功能

自动生成 API 文档（必做）

# conf.py
extensions.append('sphinx.ext.autodoc')

# 在.rst文件中使用：
.. automodule:: your_module
   :members:

九、多语言支持（可不做）

pip install sphinx-intl
sphinx-build -b gettext . _build/gettext
sphinx-intl update -p _build/gettext -l zh_CN

 十、部署文档

推荐部署平台：

• ReadTheDocs（免费托管）

• GitHub Pages

• 自建服务器

十一、常用命令速查

命令	说明
make html	生成HTML文档
make clean	清理构建文件
sphinx-apidoc -o source ../src	自动生成API文档

十二、常见问题 

Q: 中文搜索不可用？
A: 安装jieba分词器：

pip install jieba

Q: 如何添加数学公式？
A: 启用 sphinx.ext.mathjax 扩展

---

通过本教程，已经能够创建结构化的技术文档。Sphinx 的强大功能还包括版本控制集成、自定义模板、自动化构建等，可进一步探索官方文档：Sphinx — Sphinx documentation