HTML主题支持¶
0.6 新版功能.
注解
本文档提供有关创建自己的主题的信息。 如果您只想使用预先存在的HTML主题，请参阅 HTML 。
Sphinx支持通过 themes 更改其HTML输出的外观。 主题是HTML模板，样式表和其他静态文件的集合。此外，它还有一个配置文件，用于指定要继承的主题，要使用的突出显示样式以及用于自定义主题外观的选项。
主题意味着项目不知情，因此它们可以用于不同的项目而无需改变。
创建主题¶
主题采用目录或zipfile(其名称为主题名称)的形式，包含以下内容:
theme.conf文件。HTML模板，如果需要的话。
一个
static/目录，包含将在构建时复制到输出静态目录的所有静态文件。 这些可以是图像，样式，脚本文件。
theme.conf 文件是INI格式 1 (可由标准Python ConfigParser 模块读取)并具有以下结构:
[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
[options]
variable = default value
inherit 设置给出了“基本主题”或“无”的名称。 基本主题将用于查找缺少的模板(大多数主题如果使用
basic作为基本主题，则不必提供大多数模板)，其选项将被继承，并且其所有静态文件将用作好。 如果你还想继承样式表，可以在你自己的CSS’@import中包含它。stylesheet 设置给出了将在HTML标头中引用的CSS文件的名称。 如果您需要多个CSS文件，可以通过CSS’
@import包含另一个CSS文件，或者使用自定义HTML模板，根据需要添加<link rel = "stylesheet">标签。 设置html_style配置值将覆盖此设置。pygments_style 设置给出了用于突出显示的Pygments样式的名称。 这可以由用户在
pygments_style配置值中覆盖。sidebars 设置给出了逗号分隔的侧边栏模板列表，用于构建侧边栏。 这可以由用户在
html_sidebars配置值中覆盖。选项 部分包含变量名称和默认值对。 这些选项可以被用户覆盖
html_theme_options，并且可以从所有模板访问为theme_<name>。
1.7 新版功能: sidebar settings
将您的主题分发为Python包¶
作为分发主题的一种方法，您可以使用Python包。 Python包为用户带来了简单的设置方式。
要将您的主题分发为Python包，请在 setup.py 文件中定义一个名为 sphinx.html_themes 的入口点，并编写一个 setup() 函数来使用注册您的主题 add_html_theme() API:
# 'setup.py'
setup(
...
entry_points = {
'sphinx.html_themes': [
'name_of_theme = your_package',
]
},
...
)
# 'your_package.py'
from os import path
def setup(app):
app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
如果您的主题包包含两个或更多主题，请调用两次或更多次 add_html_theme() 。
1.2 新版功能: ‘sphinx_themes’entry_points 功能。
1.6 版后已移除: sphinx_themes entry_points 已被弃用。
1.6 新版功能: sphinx.html_themes entry_points 功能。
模板¶
如果你想编写自己的模板， 模板指南 指南很有用。 重要的是要记住Sphinx搜索模板的顺序:
首先，在用户的
templates_path目录中。然后，在选定的主题中。
然后，在它的基础主题，它的基地的基础主题等。
在基本主题中扩展具有相同名称的模板时，请使用主题名称作为显式目录: {％extends "basiclayout.html" ％} 。 从用户 templates_path 模板，您仍然可以使用模板文档中描述的 “exclamation mark” 语法。
静态模板¶
由于主题选项旨在让用户更轻松地配置主题，而无需编写自定义样式表，因此必须能够模拟静态文件以及HTML文件。 因此，Sphinx支持所谓的“静态模板”，就像这样:
如果主题的 static/ 目录中的文件名(或用户的静态路径中的文件名)以 _t 结尾，则它将由模板引擎处理。 _t 将从最终文件名中删除。 例如， classic 主题有一个文件 static/classic.css_t ，它使用模板将颜色选项放入样式表中。 使用经典主题构建文档时，输出目录将包含一个 _static/classic.css 文件，其中已处理所有模板标记。
- 1
它不是可执行的Python文件，而不是
conf.py，因为如果共享主题，这将带来不必要的安全风险。