HTML主题支持¶

版本0.6中的新功能。

Sphinx支持通过主题更改其HTML输出的外观。主题是HTML模板、样式表和其他静态文件的集合。此外，它有一个配置文件，它指定从哪个主题继承、使用哪个突出显示的样式、以及存在哪些选项来定制主题的外观和感觉。

主题的一个目标是与项目无关，所以它们可以用于不同的项目而不需要改变。

使用主题¶

使用现有的主题很容易。如果是内置的Sphinx主题，你只需要设置html_theme配置值。使用html_theme_options配置值，你可以设置主题特定的选项来改变外观和感觉。例如，你可以在你的conf.py中有以下内容：

html_theme = "classic"
html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

这将给你经典的主题，但具有右侧边栏和黑色背景的关系栏（位于页面顶部和底部带有导航链接的栏）。

如果不是Sphinx自带的主题，它可以是两种静态形式：目录（包含theme.conf和其他需要的文件），或具有相同内容的zip文件。任何一个都必须放在Sphinx可以找到它的地方；关于它，有配置值html_theme_path。它给出了相对于包含conf.py的目录的目录列表，其中可以包含主题目录或zip文件。例如，如果你在文件blue.zip中有一个主题，则可以将其放在包含conf.py的目录中，并使用此配置：

html_theme = "blue"
html_theme_path = ["."]

如果安装了setuptools包，第三种形式为Sphinx动态提供你的主题路径。你可以在你的setup.py文件中提供一个名为sphinx_themes的入口点部分，并写一个get_path函数，该函数必须返回包含主题的目录：

# 'setup.py'

setup(
    ...
    entry_points = {
        'sphinx_themes': [
            'path = your_package:get_path',
        ]
    },
    ...
)

# 'your_package.py'

from os import path
package_dir = path.abspath(path.dirname(__file__))
template_path = path.join(package_dir, 'themes')

def get_path():
    return template_path

版本1.2中的新功能：‘sphinx_themes’入口点功能。

内置的主题¶

主题概览

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

Sphinx自带一些主题可供选择。

这些主题是：

basic - 这是一个基本上没有花样的布局，用作其他主题的基础，也可用作自定义主题的基础。HTML包含所有重要的元素，如侧边栏和关系栏。有下面这些选项（由其他主题继承）：
- nosidebar（true或false）：不包括侧边栏。默认为False。
- sidebarwidth（整数）：边栏的宽度（以像素为单位）。（不要在值中包含px）。默认为230像素。
alabaster - Alabaster主题是一个从@kennethreitz修改的“Kr”Sphinx主题（特别是在他的Requests项目中使用），本身最初基于@ mitsuhiko的主题，用于Flask及其相关的项目。你可以在Alabaster主题页面获取选项信息。
classic - 这是经典主题，看起来像Python 2文档。它可以通过这些选项定制：
- 右侧栏（true或false）：将侧边栏放在右侧。默认为False。
- stickysidebar（true或false）：使侧边栏“固定”，以使其对于很长的内容不会滚动到视图以外。这可能无法正常工作于所有浏览器。默认为False。
- collapsiblesidebar（true或false）：添加一个实验性JavaScript代码段，通过边上的按钮使边栏可折叠。不适用于“stickysidebar”。默认为False。
- externalrefs（true或false）：外部链接与内部链接显示不同。默认为False。
还有各种颜色和字体选项可以更改颜色方案，而无需编写自定义样式表：
- footerbgcolor（CSS color）：页脚行的背景颜色。
- footertextcolor（CSS color）：页脚行的文本颜色。
- sidebarbgcolor（CSS color）：侧边栏的背景颜色。
- sidebarbtncolor（CSS color）：边栏折叠按钮的背景颜色（在collapsiblesidebar为True时使用）。
- sidebartextcolor（CSS color）：边栏的文字颜色。
- sidebarlinkcolor（CSS color）：侧边栏链接的颜色。
- relbarbgcolor（CSS color）：关系栏的背景颜色。
- relbartextcolor（CSS color）：关系栏的文本颜色。
- relbarlinkcolor（CSS color）：关联栏的链接颜色。
- bgcolor（CSS color）：正文背景颜色。
- textcolor（CSS color）：正文文本颜色。
- linkcolor（CSS color）：正文链接颜色。
- visitedlinkcolor（CSS color）：已访问链接的正文颜色。
- headbgcolor（CSS color）：标题的背景颜色。
- headtextcolor（CSS color）：标题的文本颜色。
- headlinkcolor（CSS color）：标题的链接颜色。
- codebgcolor（CSS color）：代码块的背景颜色。
- codetextcolor（CSS color）：如果突出显示样式没有设置，代码块的默认文本颜色。
- bodyfont（CSS font-family）：正常文本的字体。
- headfont（CSS font-family）：标题的字体。
sphinxdoc - 本文档使用的主题。它在右侧有一个侧边栏。目前除nosidebar和sidebarwidth之外，没有其它选项。
scrolls - 基于Jinja文档的更轻量级的主题。提供以下颜色选项：
- headerbordercolor
- subheadlinecolor
- linkcolor
- visitedlinkcolor
- admonitioncolor
agogo - 由Andi Albrecht创建的主题。支持以下选项：
- bodyfont（CSS font family）：正常文字的字体。
- headerfont（CSS font family）：标题的字体。
- pagewidth（CSS length）：页面内容的宽度，默认为70em。
- documentwidth（CSS length）：文档的宽度（无边栏），默认为50em。
- sidebarwidth（CSS length）：边栏的宽度，默认为20em。
- bgcolor（CSS color）：背景的颜色。
- headerbg（“background”的CSS值）：标题区域的背景，默认为灰色渐变。
- footerbg（CSS值为“background”）：页脚区域的背景，默认为浅灰色渐变。
- linkcolor (CSS color): Body link color.
- headercolor1，headercolor2（CSS color）：<h1>和<h2>标题的颜色
- headerlinkcolor（CSS color）：标题中反向链接的颜色。
- textalign（CSS text-align值）：文本对齐方式，默认为justify。
nature - 一个绿色的主题。目前除nosidebar和sidebarwidth之外，没有其它选项。
pyramid - 来自Pyramid web框架项目的主题，由Blaise Laflamme设计。目前除nosidebar和sidebarwidth之外，没有其它选项。
haiku - 没有侧边栏的主题，受Haiku OS用户指南启发。支持以下选项：
- full_logo（true或false，默认值False）：如果为true，标头只显示html_logo。用于大的logo。如果为false，logo （如果存在）将显示为右浮动，文档标题将放在标题中。
- textcolor、headingcolor、linkcolor、visitedlinkcolor、hoverlinkcolor：各种bod元素的颜色。
traditional - 类似于旧Python文档的主题。目前除nosidebar和sidebarwidth之外，没有其它选项。
epub - epub构建器的主题。这个主题试图节省可视空间，它是电子书阅读器上稀缺的资源。支持以下选项：
- relbar1（true或false，默认True）：如果为true，则将relbar1块插入epub输出，否则忽略。
- footer（true或false，默认值True）：如果为true，则将footer块插入epub输出，否则忽略。

bizstyle - 一个简单的蓝色主题。除nosidebar和sidebarwidth之外，还支持以下选项：
- 右侧栏（true或false）：将侧边栏放在右侧。默认为False。

版本1.3中的新功能：'alabaster'，'sphinx_rtd_theme'和'bizstyle'主题。

在版本1.3中更改：“default”主题已重命名为“classic”。'default'仍然可用，但它会发出通知，它是一个新的'alabaster'主题的别名。

创建主题¶

如上所述，主题是目录或zip文件（它们的名称就是主题得名称），包含以下内容：

一个theme.conf文件，请参阅下文。
HTML模板（如果需要）。
一个static/目录，包含将被复制到构建输出的静态目录的任何静态文件。它们可以是图像、样式、脚本文件。

theme.conf文件采用INI格式[1]（可由标准Python ConfigParser模块读取），并具有以下结构：

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename

[options]
variable = default value

inherit设置给出“基类主题”的名称，或者没有。基类主题将用于定位丢失的模板（如果大多数主题使用basic作为基类主题，则大多数主题的大部分模板不需要提供），其选项将被继承，其所有静态文件也将被使用。
stylesheet设置给出将在HTML头部引用的CSS文件的名称。如果你需要多个CSS文件，可以通过CSS'@import或者使用自定义HTML模板添加必要的<link rel="stylesheet">标签。设置html_style配置值将覆盖此设置。
pygments_style设置给出用于突出显示的Pygments样式的名称。这可以由用户在pygments_style配置值中覆盖。
options部分包含变量名称和默认值对。这些选项可以由用户在html_theme_options中覆盖，并且可以从所有模板以theme_<name>访问。

模板¶

如果你想写你自己的模板，模板指南是有帮助的。重要的是要记住的是Sphinx搜索模板的顺序：

首先，在用户的templates_path目录中。
然后，在所选主题中。
然后，在其基类主题，其基类的基类主题等。

当使用相同名称扩展基类主题中的模板时，请使用主题名称作为显式目录：{% extends "basic/layout.html" %}。从用户templates_path模板，你仍然可以使用模板文档中描述的“感叹号标记”语法。

静态模板¶

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

如果主题的static /目录中（或在用户的静态路径中）的文件名称以_t结束，它将由模板引擎处理。_t将从最终文件名中删除。例如，classic主题有一个文件static/classic.css_t，它使用模板将颜色选项放入样式表。当使用经典主题构建文档时，输出目录将包含一个_static/classic.css文件，其中已处理所有模板标记。

[1]	与`conf.py`不同，它不是一个可执行的Python文件，因为如果主题是共享的，那将会造成不必要的安全风险。

第三方主题¶

主题概览

sphinx_rtd_theme

sphinx_rtd_theme

sphinx_rtd_theme - Read the Docs的Sphinx主题。这是一个为readthedocs.org设计的移动友好的sphinx主题。查看readthedocs.org上的工作演示。你可以在Read the Docs Sphinx主题页面获取安装和选项信息。

在版本1.4中更改： sphinx_rtd_theme成为可选。

目录

上一主题

下一主题

这一页