5.1. Sphinx文档项目配置¶
此部分内容说明使用 Sphinx 进行文档项目维护时的技术要求。
5.1.1. 配置¶
配置文件 /source/conf.py 在构建时作为Python代码执行
(使用 execfile() , 并且当前目录设置为其包含目录)。
项目信息¶
project |
记录的项目名称。 |
author |
该文件的作者姓名。 默认值为 unknown |
copyright |
2020, Author Name 风格的版权声明 |
version |
主要项目版本, 用作 |version| 的替代品。 例如, 对于Python文档, 这可能类似于 2.6 。 |
release |
完整的项目版本, 用作 |release| 的替代品, 例如在HTML模板中。 例如, 对于Python文档, 这可能类似于 2.6.0rc1 。 如果你不需要在 version 和 release 之间提供分隔, 只需将它们设置为相同的值即可。 |
一般配置项¶
extensions 可以是Sphinx(名为 sphinx.ext.*)或自定义的扩展。
请注意, 如果扩展名位于另一个目录中, 则可以在conf文件中扩展 sys.path(使用绝对路径)。
如果扩展路径是相对于 configuration directory , 使用 os.path.abspath()
import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']
这样, 你可以从子目录 sphinxext 加载一个名为 extname 的扩展名。
source_suffix 源文件的文件扩展名。 Sphinx将具有此后缀的文件视为源。
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'restructuredtext',
'.md': 'markdown',
}
可以使用源解析器扩展添加新文件类型。
source_encoding 所有reST源文件的编码。推荐的编码和默认值是 ‘utf-8-sig’ 。
master_doc 主目录文件名，默认为index
templates_path 包含额外模板的路径列表(覆盖内置/主题特定模板的模板)。相对路径被视为相对于配置目录。
由于这些文件不是要构建的, 因此它们会自动添加到 exclude_patterns 中.
numfig 如果为 True ， 则数字, 表格和代码块如果有标题则会自动编号。 numref 角色已启用。
highlight_language
用于突出显示源代码的默认语言。默认语言为 ‘python3’ 。 代码高亮
highlight_options
HTML输出选项¶
这些选项会影响HTML以及HTML帮助输出, 以及使用Sphinx的HTMLWriter类的其他构建器。
html主题 html_theme
页面主题模板，默认 alabaster 。 内置主题信息
# html_theme_options 所选主题外观的选项字典。
# html_copy_source 默认为true, reST源包含在HTML构建中 _sources/name
# html_show_sourcelink 默认为true(并且 html_copy_source 也为 true ), 则指向reST源的链接将添加到侧栏。
HTML主题¶
Sphinx支持通过 themes 更改其HTML输出的外观。
主题是HTML模板, 样式表和其他静态文件的集合。此外, 它还有一个配置文件, 用于指定要继承的主题, 要使用的突出显示样式以及用于自定义主题外观的选项。
也可以自己 制作主题
使用（配置）主题
使用内置主题
设置 conf.py 中 html_theme 的值即可
html_theme = 'classic'
修改主题的一些配置选项，修改 html_theme_options 配置项，
对于使用的主题适用于哪些修改，视具体主题而定。
html_theme_options = {
"rightsidebar": "true",
"relbarbgcolor": "black"}