HTML主题开发

Added in version 0.6.

备注

本文档提供有关创建自己主题的信息。如果您只想使用预先存在的HTML主题，请参阅 HTML主题化 .

sphinx支持通过 主题 . 主题是HTML模板、样式表和其他静态文件的集合。此外，它还有一个配置文件，指定要继承的主题、要使用的突出显示样式以及自定义主题外观的选项。

主题意味着项目不知道，所以它们可以用于不同的项目而不改变。

备注

见 Sphinx扩展API 了解更多可能有助于发展主题的信息。

创作主题

主题采用目录或压缩文件（名称为主题名称）的形式，包含以下内容：

• A theme.conf 文件。

• HTML模板（如果需要）。

• A 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

• 这个 继承 设置给出“基本主题”的名称，或 none . 基本主题将用于查找缺少的模板（如果大多数主题使用，则不必提供大多数模板 basic 作为基本主题），它的选项将被继承，并且它的所有静态文件也将被使用。如果还想继承样式表，请通过css将其包含在内。 @import 你自己的。

• 这个 stylesheet 设置提供了一个以逗号分隔的CSS文件名列表，该列表将在HTML头中引用。您还可以使用css的 @import 技术，以包含一个或另一个，或使用添加了 <link rel="stylesheet"> 根据需要添加标签。设置 html_style 配置值将覆盖此设置。

• 这个 pygments_style 设置提供用于突出显示的Pygments样式的名称。用户可以在 pygments_style 配置值。

• 这个 pygments_dark_style 设置给出了在CSS媒体查询时用于突出显示的Pygments样式的名称 (prefers-color-scheme: dark) 计算结果为True。它被注入页面，使用 add_css_file() 。

• 这个 侧栏 设置提供用于构造侧栏的侧栏模板的逗号分隔列表。用户可以在 html_sidebars 配置值。

• 这个 选项 节包含变量名和默认值对。用户可以在 html_theme_options 并且可以从所有模板访问 theme_<name> .

Added in version 1.7: 边栏设置

在 5.1 版本发生变更: StyleSheet设置接受多个CSS文件名

将主题作为python包分发

作为分发主题的一种方式，您可以使用一个Python包。这使得用户更容易设置您的主题。

要将您的主题作为一个Python包分发，请定义一个名为 sphinx.html_themes 在你的 pyproject.toml 文件，并编写一个 setup() 函数来注册主题。 add_html_theme() 接口：

# pyproject.toml

[project.entry-points."sphinx.html_themes"]
name_of_theme = "your_theme_package"

# your_theme_package.py
from os import path

def setup(app):
    app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))

如果主题包包含两个或更多主题，请致电 add_html_theme() 两次以上。

Added in version 1.2: “Sphinx主题”入口点功能。

自 1.6 版本弃用: sphinx_themes 入口点已被弃用。

Added in version 1.6: sphinx.html_themes 入口点功能。

模板法

这个 guide to templating 如果您想要编写自己的模板，这将非常有用。重要的是要记住Sphinx搜索模板的顺序：

• 首先，在用户的 templates_path 目录。

• 然后，在选定的主题中。

• 然后，在其基础主题、基础主题等方面。

在使用相同名称扩展基本主题中的模板时，请使用主题名称作为显式目录： {% extends "basic/layout.html" %} 。来自用户 templates_path 模板，您仍然可以使用“感叹号”语法作为 described in the templating document 。

静态模板

因为主题选项是为了让用户更容易地配置主题，而不必编写自定义样式表，所以必须能够对静态文件和HTML文件进行模板化。因此，sphinx支持所谓的“静态模板”，如下所示：

中的文件的名称 static/ 主题的目录(或在用户的静态路径中)以 _t ，它将由模板引擎处理。这个 _t 将从最终文件名起保留。例如， classic 主题有一个文件 static/classic.css_t 它使用模板将颜色选项放入样式表。当使用经典主题生成文档项目时，输出目录将包含 _static/classic.css 已处理所有模板标记的文件。

在HTML模板中使用自定义页面元数据

中的任何键/值对 field lists 放置的 之前 在中构建页面时，Jinja模板将可以使用该页面的标题 meta 属性。例如，如果页面的第一个标题前有以下文本：

:mykey: My value

My first title
--------------

然后可以在Jinja模板中访问它，如下所示：

{%- if meta is mapping %}
    {{ meta.get("mykey") }}
{%- endif %}

注意检查 meta 是一个字典（Jinja术语中的“映射”），以确保以这种方式使用它是有效的。

定义自定义模板函数

有时，用Python定义您自己的函数，然后在模板中使用它是很有用的。例如，如果您想插入一个模板值，该值的逻辑依赖于项目中的用户配置，或者如果您希望在模板中包含非平凡的检查并为不正确的配置提供友好的错误消息。

要定义自己的模板函数，需要在模块内定义两个函数：

• A 页面上下文事件处理程序 （或） 注册 )功能。它连接到 Sphinx 通过事件回调应用程序。

• A 模板函数 你将在你的Jinja模板中使用。

首先，定义registration函数，它接受 html-page-context .

在registration函数中，定义要在Jinja中使用的模板函数。template函数应该返回一个字符串或Python对象（列表、字典），其中包含Jinja在模板化过程中使用的字符串

备注

模板函数可以访问传递给注册函数的所有变量。

在注册函数的末尾，使用 context['template_func'] = template_func .

最后，在你的分机 setup() 函数，添加注册函数作为 html-page-context .

# The registration function
 def setup_my_func(app, pagename, templatename, context, doctree):
     # The template function
     def my_func(mystring):
         return "Your string is %s" % mystring
     # Add it to the page's context
     context['my_func'] = my_func

 # Your extension's setup function
 def setup(app):
     app.connect("html-page-context", setup_my_func)

现在，您可以在jinja中访问此函数，如下所示：

<div>
{{ my_func("some string") }}
</div>

将您自己的静态文件添加到构建资源中

默认情况下，Sphinx将静态文件复制到 static/ 模板目录的目录。但是，如果您的包需要将静态文件放在 static/ 由于某些原因，您需要将它们复制到 _static/ 在生成时通过事件挂钩手动执行的HTML输出目录。以下是实现这一点的代码示例：

from os import path
from sphinx.util.fileutil import copy_asset_file

def copy_custom_files(app, exc):
    if app.builder.format == 'html' and not exc:
        staticdir = path.join(app.builder.outdir, '_static')
        copy_asset_file('path/to/myextension/_static/myjsfile.js', staticdir)

def setup(app):
    app.connect('build-finished', copy_custom_files)

基于用户配置注入JavaScript

如果您的扩展使用JavaScript，那么允许用户使用Sphinx配置来控制它的行为是很有用的。但是，如果JavaScript以静态库的形式出现（它不是用Jinja构建的），这可能很难做到。

有两种根据用户配置将变量注入JavaScript空间的方法。

首先，你可以附加 _t 扩展名中包含的所有静态文件的末尾。这将导致Sphinx使用模板引擎处理这些文件，从而允许您嵌入变量和控制行为。

例如，以下JavaScript结构：

mymodule/
├── _static
│   └── myjsfile.js_t
└── mymodule.py

将导致在HTML的生成输出中放置以下静态文件：

_build/
└── html
    └── _static
        └── myjsfile.js

见 静态模板 更多信息。

其次，您可以使用 Sphinx.add_js_file() 方法，而不将其指向文件。通常，此方法用于将新的JavaScript文件插入到站点中。但是，如果您这样做了 not 传递一个文件路径，而不是将一个字符串传递给“Body”参数，然后该文本将作为JavaScript插入到您的站点头部。这使您可以将变量从Python插入到项目的JavaScript中。

例如，以下代码将读入用户配置的值，然后将该值作为JavaScript变量插入，您的扩展的JavaScript代码可能会使用该变量：

# This function reads in a variable and inserts it into JavaScript
def add_js_variable(app):
    # This is a configuration that you've specified for users in `conf.py`
    js_variable = app.config['my_javascript_variable']
    js_text = "var my_variable = '%s';" % js_variable
    app.add_js_file(None, body=js_text)
# We connect this function to the step after the builder is initialized
def setup(app):
    # Tell Sphinx about this configuration variable
    app.add_config_value('my_javascript_variable', 0, 'html')
    # Run the function after the builder is initialized
    app.connect('builder-inited', add_js_variable)

因此，在您的主题中，您可以使用依赖于此变量存在的代码。用户可以通过在 conf.py 文件。

[1]

它不是可执行的python文件，而不是 conf.py ，因为如果共享主题，这将带来不必要的安全风险。