深入解析：sphinx(1)基础使用

深入解析：sphinx(1)基础使用

(1)基础介绍

：Once Day Date：2025年11月17日

漫漫长路，才刚刚开始…

参考文档:

1. 介绍

是一个强大的文档生成工具，它诞生于技术文档需求日益增长的背景下，为开发者提供了一种优雅而高效的方式来创建、管理和发布各类文档。

的故事始于2008年，当时社区面临着一个挑战：需要一个更好的系统来编写官方文档。Georg 正是在这样的背景下创建了，最初就是为了满足语言本身的文档需求。这个工具的名字灵感来源于埃及的狮身人面像（），象征着智慧与力量的结合。

随着时间推移，逐渐从社区的一个内部工具，发展成为一个广泛使用的通用文档解决方案。它的成功不仅体现在生态系统中，还扩展到了许多其他编程语言和技术领域。如今，无论是开源项目还是企业级应用，都成为了技术文档的首选工具之一。

的魅力在于它将简单的使用体验与强大的功能完美结合。它的核心价值包括：

丰富的输出格式：可以将同一份源文档转换成多种格式，包括HTML、PDF、ePub等，满足不同场景下的阅读需求。结构化文档：它支持文档的层次结构组织sphinx mysql python，自动生成目录、索引和交叉引用，使得复杂的文档也能保持清晰的结构。代码文档自动化：可以从代码注释中自动提取文档sphinx mysql python，为API文档的维护提供了极大便利。强大的扩展系统：通过丰富的扩展，可以实现语法高亮、数学公式渲染、图表生成等高级功能。国际化支持：它内建了对多语言文档的支持，便于项目文档的国际化。

文档生成工具的领域中，并非独行者。各种工具各有所长，适合不同的场景和偏好：

每个工具都有自己的生态系统和社区支持，选择时应根据项目需求、团队技能和文档复杂度来考量。

2. 安装与简单使用

在-04系统上使用下面命令进行安装：

sudo apt install python3-sphinx

接着，在项目目录中初始化：

onceday->sphinx:$ mkdir docs
onceday->sphinx:$ cd docs
onceday->sphinx:$ sphinx-quickstart
Welcome to the Sphinx 7.2.6 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
The project name will occur in several places in the built documentation.
> Project name: ease
> Author name(s): onceday
> Project release []: 1.0.0
If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN
Creating file /home/onceday/ease/sphinx/docs/source/conf.py.
Creating file /home/onceday/ease/sphinx/docs/source/index.rst.
Creating file /home/onceday/ease/sphinx/docs/Makefile.
Creating file /home/onceday/ease/sphinx/docs/make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file /home/onceday/ease/sphinx/docs/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

在交互式设置中，我们可以配置项目名称、作者、版本等信息。完成后深入解析：sphinx(1)基础使用，会生成基本的文档结构。

onceday->docs:$ ls -al
total 24
drwxrwxr-x 4 onceday onceday 4096 Nov 17 12:39 .
drwxrwxr-x 3 onceday onceday 4096 Nov 17 12:37 ..
drwxrwxr-x 4 onceday onceday 4096 Nov 17 12:50 build
-rw-rw-r-- 1 onceday onceday  804 Nov 17 12:39 make.bat
-rw-rw-r-- 1 onceday onceday  638 Nov 17 12:39 Makefile
drwxrwxr-x 4 onceday onceday 4096 Nov 17 12:49 source
onceday->docs:$ ls -al source/
total 28
drwxrwxr-x 4 onceday onceday 4096 Nov 17 12:49 .
drwxrwxr-x 4 onceday onceday 4096 Nov 17 12:39 ..
-rw-rw-r-- 1 onceday onceday  934 Nov 17 12:39 conf.py
-rw-rw-r-- 1 onceday onceday  514 Nov 17 12:47 index.rst
drwxrwxr-x 2 onceday onceday 4096 Nov 17 12:39 _static
drwxrwxr-x 2 onceday onceday 4096 Nov 17 12:39 _templates

目录和文件结构说明：

现在，编辑index.rst文件，添加项目的概述：

rst
欢迎来到EASE项目文档
=========================
EASE是一个简单而强大的C/C++库，提供一系列基础能力组件用于开发高级业务APP。
.. toctree::
   :maxdepth: 2
   :caption: 目录:
   installation
   usage
   api

创建相应的文档文件，例如.rst：

安装指南
========
使用apt安装
-----------
.. code-block:: bash
apt install ease
从源码安装
---------
.. code-block:: bash
   git clone https://github.com/example/ease.git
   cd ease
   make build && sudo make install

最后，生成HTML文档：

make html

打开/html/index.html，会看到一个精美的文档网站，包含目录、导航和搜索功能。

3. 本地预览(-)

在-04系统上使用下面命令进行安装：

sudo apt install python3-sphinx-autobuild

– build/html 是一个非常实用的 开发工具命令，它能显著提升文档编写的效率和体验。

使用 – 的主要优势在于它创建了一个”所见即所得”的文档编辑环境，让你无需手动执行 make html 命令并刷新浏览器。这大大提高了文档编写的流畅性，特别适合以下场景：

4. 插件系统

的强大之处在于其可扩展的插件系统，通过这些插件（称为”扩展”），可以大幅增强文档的功能和外观。

本身支持多语言，对于中文文档，需要在 conf.py 中进行设置而非安装额外插件：

# 设置语言为中文
language = 'zh_CN'
# 配合中文搜索
html_search_language = 'zh'
html_search_options = {'type': 'jieba'}

常用功能扩展插件：

# 在conf.py中设置
html_theme = 'sphinx_rtd_theme'

# 在conf.py中启用
extensions = ['sphinx_copybutton']

# 在conf.py中启用
extensions = ['sphinxcontrib.mermaid']

# 在conf.py中启用
extensions = ['sphinx_markdown_tables']

API文档自动生成插件：

# 内置扩展，在conf.py中启用
extensions = ['sphinx.ext.autodoc']

# 在conf.py中启用
extensions = ['autoapi.extension']

支持插件：

# 在conf.py中启用
extensions = ['recommonmark']

# 在conf.py中启用
extensions = ['myst_parser']

增强交互性插件：

# 在conf.py中启用
extensions = ['sphinx_tabs.tabs']

# 在conf.py中启用
extensions = ['sphinx_togglebutton']

5. 支持文档

MyST- 是目前最推荐的 解析器，它提供了比 更完整的 支持：

pip install myst-parser

编辑 conf.py 文件深入解析：sphinx(1)基础使用，添加 MyST- 的支持：

source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
# 启用所有 MyST 语法扩展
myst_enable_extensions = [
'amsmath',
'colon_fence',
'deflist',
'dollarmath',
'fieldlist',
'html_admonition',
'html_image',
'linkify',
'replacements',
'smartquotes',
'strikethrough',
'substitution',
'tasklist',
]
# 可选：设置渲染围栏代码块的方式
myst_fence_as_directive = True

添加一些有用的插件增强 体验：

# 代码块复制按钮
pip install sphinx-copybutton
# 表格支持增强
pip install sphinx-markdown-tables
# 选项卡支持
pip install sphinx-tabs
# 代码高亮增强
pip install pygments

更新 conf.py 添加这些插件：

extensions = [
'myst_parser',
'sphinx_copybutton',
'sphinx_markdown_tables',
'sphinx_tabs.tabs',
# 其他已有扩展...
]

6. 项目实战6.1 安装所有需要软件包

sudo apt install python3-sphinx # shpinx主包
sudo apt install python3-sphinx-autobuild # 本地预览
sudo apt install python3-myst-parser # markdown支持
sudo apt install python3-sphinx-copybutton # 代码块复制按钮
sudo apt install python3-sphinx-markdown-tables # 表格支持增强
sudo apt install python3-sphinx-tabs # 选项卡支持
sudo apt install python3-pygments # 代码高亮增强
# 文档主题
sudo apt install python3-sphinx-rtd-theme # 安装 Read the Docs 主题
sudo apt install python3-sphinx-book-theme # 安装 Book 主题

注意：这里直接安装到全局目录里面，有一些第三方工作包不在系统软件包里面，因此对于复杂的配置场景，还是需要使用 venv环境进行安装。

# 安装venv包
sudo apt install python3.12-venv
# 创建虚拟环境
python3 -m venv sphinx-env
source sphinx-env/bin/activate
# 设置镜像源(下载如果出错, 可以多换几个)
pip config set global.index-url http://mirrors.aliyun.com/pypi/simple
pip config set install.trusted-host mirrors.aliyun.com

然后按照 相关包：

pip install sphinx # shpinx主包
pip install sphinx-autobuild # 本地预览
pip install myst-parser # markdown支持
pip install sphinx-copybutton # 代码块复制按钮
pip install sphinx-markdown-tables # 表格支持增强
pip install sphinx-tabs # 选项卡支持
pip install pygments # 代码高亮增强
pip install linkify-it-py # 工具库
# 文档主题
pip install sphinx-rtd-theme # 安装 Read the Docs 主题
pip install sphinx-book-theme # 安装 Book 主题
pip install furo # 安装 Furo 主题
pip install shibuya # 安装 Shibuya 主题

Read the Docs 主题：最流行的技术文档主题，清晰简洁，广泛兼容，良好的移动端支持，嵌套导航，适用于技术参考文档，API 文档。

Furo 主题：现代、简约的设计，专注于阅读体验，优雅的排版，明暗模式，高度可定制。文字内容为主的文档，书籍风格的项目

主题：受日本设计影响的现代主题，强调视觉层次，精美的视觉设计，完善的响应式布局sphinx mysql python，丰富的组件，注重设计的文档，产品文档。

Book 主题：类似教科书的布局，侧重于学习体验，完善的导航结构，章节组织，交互式功能，适用于教程，指南，学习资料。

6.2 配置文件

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = "ease"
copyright = "2025, onceday"
author = "onceday"
release = "1.0.0"
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
"myst_parser",
"sphinx_copybutton",
"sphinx_markdown_tables",
"sphinx_tabs.tabs",
]
# 将 .md 文件映射到 MyST 解析器
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
# 启用所有 MyST 语法扩展
myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"fieldlist",
"html_admonition",
"html_image",
"linkify",
"replacements",
"smartquotes",
"strikethrough",
"substitution",
"tasklist",
]
# 可选：设置渲染围栏代码块的方式
myst_fence_as_directive = [
"mermaid",  # 例如将 ```mermaid 作为 directive 处理
"math",
]
templates_path = ["_templates"]
exclude_patterns = []
language = "zh_CN"
html_search_language = "zh"
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "furo"
html_theme_options = {
"sidebar_hide_name": False,
"navigation_with_keys": True,
# "announcement": "这是一个使用 Furo 主题的示例文档",
# "light_css_variables": {
#     "color-brand-primary": "#7C4DFF",
#     "color-brand-content": "#7C4DFF",
# },
}
html_static_path = ["_static"]

6.3 新增文档

新增文档：

(sphinx-env) onceday->docs:$ cat source/API参考.md
# API参考
(sphinx-env) onceday->docs:$ cat source/使用介绍.md
# 使用介绍

然后本地预览：