HTML主题化

Sphinx为基于HTML和HTML的格式提供了许多构建器。

Builders

待处理

当“构建者”文档被拆分时填充。

主题

0.6 新版功能.

注解

本节提供有关使用现有HTML主题的信息。如果您希望创建自己的主题,请参阅 HTML主题开发 .

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

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

使用主题

使用A theme provided with Sphinx 很容易。由于不需要安装这些,您只需要设置 html_theme 配置值。例如,要启用 classic 主题,将以下内容添加到 conf.py ::

html_theme = "classic"

还可以使用 html_theme_options 配置值。这些选项通常用于更改主题的外观和感觉。例如,要将侧边栏放在右侧,并为关系栏添加黑色背景(在页面顶部和底部具有导航链接的栏),请添加以下内容 conf.py ::

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

如果主题不随sphinx一起提供,它可以是两种静态形式,也可以是一个python包。对于静态窗体,目录(包含 theme.conf 以及其他需要的文件),或者支持内容相同的zip文件。目录或zipfile必须放在sphinx可以找到它的地方;为此,有config值 html_theme_path . 这可以是目录列表,相对于包含 conf.py ,可以包含主题目录或zip文件。例如,如果文件中有主题 blue.zip ,您可以将其放在包含 conf.py 并使用此配置:

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

第三种形式是python包。如果要使用的主题是作为python包分发的,则可以在安装后使用它

# installing theme package
$ pip install sphinxjp.themes.dotted

安装后,可以使用与基于目录或ZipFile的主题相同的方式:

html_theme = "dotted"

有关主题设计的更多信息,包括有关编写自己主题的信息,请参阅 HTML主题开发 .

建筑主题

主题概述

alabaster

雪白石膏

classic

经典

sphinxdoc

SphinxDOC

scrolls

卷轴

agogo

阿盖奥

traditional

传统的

nature

自然

haiku

俳句

pyramid

金字塔

bizstyle

双柱式

Sphinx有多种主题可供选择。

这些主题包括:

basic

这是一个基本上没有样式的布局,用作其他主题的基础,也可用作自定义主题的基础。HTML包含所有重要元素,如侧边栏和关系栏。有以下选项(由其他主题继承):

  • 不带边框的 (对或错):不包括侧边栏。默认为 False .

  • 边宽 (int或str):边栏的宽度(像素)。这可以是一个int,它被解释为像素或有效的css维度字符串,如“70em”或“50%”。默认为230像素。

  • body_min_width (int或str):文档正文的最小宽度。这可以是一个int,它被解释为像素或有效的css维度字符串,如“70em”或“50%”。如果不需要宽度限制,请使用0。默认值可能取决于主题(通常是450像素)。

  • body_max_width (int或str):文档正文的最大宽度。这可以是一个int,它被解释为像素或有效的css维度字符串,如“70em”或“50%”。如果不需要宽度限制,请使用“无”。默认值可能取决于主题(通常为800px)。

  • navigation_with_keys (正确或错误):允许使用键盘的左右箭头导航到上一页/下一页。默认为 False .

  • globaltoc_collapse (正确或错误):仅在 globaltoc.html (见 html_sidebars )默认为 True .

    3.1 新版功能.

  • globaltoc_includehidden (正确或错误):甚至在 globaltoc.html (见 html_sidebars )包括在 :hidden:toctree 指令。默认为 False .

    3.1 新版功能.

  • globaltoc_maxdepth (int):目录树的最大深度 globaltoc.html (见 html_sidebars ). 将其设置为-1以允许无限深度。默认为在toctree指令中选择的最大深度。

    3.2 新版功能.

alabaster

Alabaster theme 是来自@kennethreitz的一个修改过的“kr”sphinx主题(特别是在他的请求项目中使用),它最初是基于@mituhiko用于烧瓶和相关项目的主题。参考其 installation page 有关如何配置的信息 html_sidebars 以供使用。

classic

这是经典的主题,看起来像 the Python 2 documentation . 它可以通过以下选项进行定制:

  • 右导航 (正确或错误):将侧边栏放在右侧。默认为 False .

  • 粘滞边栏 (正确或错误):将侧边栏设为“固定”,这样它就不会滚动出长正文内容的视图。这可能不适用于所有浏览器。默认为 False .

  • 可折叠的侧栏 (对或错):添加 实验的 一个JavaScript代码段,它通过侧边的按钮使侧边栏可折叠。默认为 False .

  • 外部参考文献 (正确或错误):显示不同于内部链接的外部链接。默认为 False .

还有各种颜色和字体选项,可以在不编写自定义样式表的情况下更改颜色方案:

  • 鞋底颜色 (CSS颜色):页脚行的背景色。

  • 脚注文本颜色 (CSS颜色):页脚行的文本颜色。

  • 边框颜色 (CSS颜色):边栏的背景色。

  • 边框颜色 (CSS颜色):侧边栏折叠按钮的背景色(用于 可折叠的侧栏True

  • 边栏文本颜色 (CSS颜色):边栏的文本颜色。

  • 边栏链接颜色 (CSS颜色):边栏的链接颜色。

  • 重色 (CSS颜色):关系栏的背景色。

  • 文本颜色 (CSS颜色):关系栏的文本颜色。

  • 重新链接颜色 (CSS颜色):关系栏的链接颜色。

  • 双色 (CSS颜色):正文背景色。

  • 字体颜色 (CSS颜色):正文文本颜色。

  • 链接颜色 (CSS颜色):正文链接颜色。

  • 可见链接颜色 (CSS颜色):已访问链接的正文颜色。

  • 头饰颜色 (CSS颜色):标题的背景色。

  • 头尾颜色 (CSS颜色):标题的文本颜色。

  • 头色 (CSS颜色):标题的链接颜色。

  • 余数颜色 (CSS颜色):代码块的背景色。

  • 钴色 (CSS颜色):代码块的默认文本颜色,如果突出显示样式没有不同的设置。

  • 字体 (CSS字体系列):普通文本的字体。

  • 头型字体 (css字体系列):标题字体。

sphinxdoc

此文档最初使用的主题。它在右边有一个侧边栏。目前没有其他选择 不带边框的边宽 .

注解

Sphinx文档现在使用 an adjusted version of the sphinxdoc theme .

scrolls

更轻的主题,基于 the Jinja documentation . 以下颜色选项可用:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

安迪·阿尔布雷特创作的主题。支持以下选项:

  • 字体 (CSS字体系列):普通文本的字体。

  • 头字型 (css字体系列):标题字体。

  • 页宽 (css length):页面内容的宽度,默认为70em。

  • 文档宽度 (css length):文档宽度(不带侧边栏),默认为50em。

  • 边宽 (css length):边栏的宽度,默认为20em。

  • 右导航 (正确或错误):将侧边栏放在右侧。默认为 True .

  • 双色 (CSS颜色):背景色。

  • 头标 (css value for“background”):标题区域的背景,默认为灰色渐变。

  • 福特伯格 (css value for“background”):页脚区域的背景,默认为浅灰色渐变。

  • 链接颜色 (CSS颜色):正文链接颜色。

  • 头色1头色2 (CSS颜色):<h1>和<h2>标题的颜色。

  • 头色 (css color):标题中的backreference链接的颜色。

  • 织构 (CSS) text-align 值):正文的文本对齐方式,默认为 justify .

nature

绿色主题。目前没有其他选择 不带边框的边宽 .

pyramid

由BlaiseLaflamme设计的金字塔网络框架项目的主题。目前没有其他选择 不带边框的边宽 .

haiku

没有侧边栏的主题灵感来自 Haiku OS user guide . 支持以下选项:

  • full_logo (正确或错误,默认 False ):如果为真,则标题将仅显示 html_logo . 大标志用这个。如果这是错误的,标志(如果存在)将显示为浮动右,文档标题将放在标题中。

  • 字体颜色标题颜色链接颜色可见链接颜色霍夫林颜色 (CSS颜色):各种身体元素的颜色。

traditional

类似于旧的Python文档的主题。目前没有其他选择 不带边框的边宽 .

epub

EPUB生成器的主题。这个主题试图节省可视空间,这是电子书阅读器上的一个稀疏资源。支持以下选项:

  • RelBAR1 (正确或错误,默认 True ):如果这是真的,则 relbar1 块插入到EPUB输出中,否则它将被省略。

  • 页脚 (正确或错误,默认 True ):如果这是真的,则 footer 块插入到EPUB输出中,否则它将被省略。

bizstyle

一个简单的蓝色主题。除此之外,还支持以下选项 不带边框的边宽

  • 右导航 (正确或错误):将侧边栏放在右侧。默认为 False .

1.3 新版功能: “alabaster”、“Sphinx”和“商业风格”主题。

在 1.3 版更改: “默认”主题已重命名为“经典”。默认值“仍然可用,但是它会发出一个通知,说明它是新“alabaster”主题的别名。

第三方主题

主题概述

sphinx_rtd_theme

sphinx_rtd_theme

有许多第三方主题可用。其中一些是通用的,而另一些是特定于单个项目的。下面列出了第三方主题的一部分。在上可以找到更多 PyPI, GitHub, GitLabsphinx-themes.org.

sphinx_rtd_theme

Read the Docs Sphinx Theme. This is a mobile-friendly sphinx theme that was made for readthedocs.org. View a working demo over on readthedocs.org. You can get install and options information at Read the Docs Sphinx Theme 页。

在 1.4 版更改: sphinx_rtd_theme 已成为可选的。