夜雨聆风
使用Sphinx构建软件说明书(2):配置文件
使用Sphinx构建软件说明书（2）：配置文件
微信公众号：生信小知识
关注可了解更多的生物信息学教程及知识。问题或建议，请公众号留言;
目录
前言1. Sphinx配置2. 项目信息3. 一般配置项4. HTML输出选项后记
前言
我决定使用Sphinx对开发的软件包写一个说明书，这里记录我学习Sphinx的记录。
所有知识来源：
-
https://www.osgeo.cn/sphinx-note/intro.html -
Sphinx 1.3.1 中文手册 (推荐查看)
已发布教程：
1. Sphinx配置
我们用 sphinx-quickstart 帮我生成了下面几个文件：
Makefile
-
build目录：空白 make.batsource 目录-
_static：用于存放图片之类的多媒体文件 -
_templates： -
conf.py：配置文件
-
index.rst：主页文件
$ tree
.
|-- Makefile
|-- README.md
|-- build
|-- make.bat
`-- source
|-- _static
|-- _templates
|-- conf.py
`-- index.rst
我们再看看配置文件具体长什么样：
# 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
import sphinx_rtd_theme
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'Try Sphinx'
copyright = '2025, fatyang'
author = 'fatyang'
release = 'V1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = []
templates_path = ['_templates']
exclude_patterns = []
language = 'zh_CN'
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']
而根据前面的章节中，我们大概知道了对于生成的文档而言，主要的美化工作、格局配置等都依赖于配置文件。
这里我们就对Sphinx配置进行详细探索。
2. 项目信息
-
project：项目名称 -
author：该文件的作者姓名 -
copyright：2020, Author Name 风格的版权声明 -
version：主要项目版本, 用作 version的替代 -
release：完整的项目版本, 用作 release的替代
详细信息可以查阅：https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
3. 一般配置项
-
extensions：扩展，如若指定，需保证其已经被安装。
-
source_suffix：源文件的文件扩展名， Sphinx将具有此后缀的文件视为源。
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
} -
source_encoding：所有
rst源文件的编码，推荐的编码和默认值是 ‘utf-8-sig’ 。 -
master_doc：主目录文件名，默认为index
-
exclude_patterns：查找源文件时应排除的glob样式模式列表。
-
templates_path：包含额外模板的路径列表，使用相对路径（相对于配置目录）。
-
rst_epilog：一串reStructuredText，它将添加到每个读取的源文件的末尾。例如：
rst_epilog = "end" -
rst_prolog：一串reStructuredText，它将添加到每个读取的源文件的开头。例如：
rst_epilog = "begin" -
suppress_warnings：用于禁止任意警告消息的警告类型列表。
-
numfig：如果为 True，那么图片、表格和代码块如果有标题则会自动编号。
-
numfig_format： 默认是将 ‘figure’ 映射为 Fig. %s，‘table’ 映射为 Table %s，‘code-block’ 映射为 Listing %s 和 ‘section’ 映射为 ‘Section’ 。
numfig_format = {
'code-block': 'Listing %s',
'figure': 'Fig. %s',
'section': 'Section',
'table': 'Table %s',
} -
numfig_secnum_depth：用于标注章节数字的位数
-
设置为 0：编号类似1，2，3… -
设置为 1：编号类似x.1，x.2，x.3… （x代表了章节数字）【默认模式】 -
设置为 2：编号类似x.y.1，x.y.2，x.y.3… （x代表了章节数字，y代表小节） -
show_authors：是否在构建的文件中展示作者，默认 False
-
language：文档编写的语言，默认为 en
详细信息可以查阅：https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
4. HTML输出选项
-
html_theme：页面主题模板，默认是 alabaster。自带的主题包括：basic, alabaster, sphinx_rtd_theme, classic, sphinxdoc, scrolls, agogo, traditional, nature, haiku, pyramid, bizstyle, epub -
html_theme_path：包含自定义主题的路径列表 -
html_title：使用Sphinx内置模板生成的html页面的title。默认 project release documentation -
html_logo：文档徽标的路径，logo会被放在侧边栏的顶部，宽度不应超过200像素，使用相对路径（相对于配置目录）。默认值:None -
html_favicon：文档的favicon。它应该是一个Windows风格的图标文件(.ico)，大小为16×16或32×32像素。默认值: None 。 -
html_static_path：包含自定义静态文件的路径列表，使用相对路径（相对于配置目录）。 -
html_show_copyright：在HTML Footer显示 “(C) Copyright …”, 默认True -
html_show_sphinx：在HTML Footer显示 “Created using Sphinx” ,”Built with Sphinx”，默认True -
html_output_encoding：HTML输出文件的编码。默认为 ‘utf-8’ -
html_secnumber_suffix：章节编号的后缀（最后一个，与章节标题相连的部分），默认是 ” .“，比如 “2.1.1.章节标题”
详细信息可以查阅：https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
后记
这里我们重点记录了一些构建文档网页时的配置设置，后面我们则进一步对构建过程中涉及到的文件和命令进行一定的探索~
