HTML

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

生成器

待处理

在 ‘builders’ 文档被拆分时填充.

主题

0.6 新版功能.

注解

本节提供有关使用预先存在的HTML主题的信息. 如果您想创建自己的主题, 请参阅 HTML主题支持.

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

主题意味着项目不知情, 因此它们可以用于不同的项目而无需改变.

使用主题

使用 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文件. 必须将目录或zip文件放在Sphinx可以找到的位置;为此, 有配置值 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

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

sphinx 有多种主题可供选择

这些主题是:

basic

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

  • nosidebar (true or false): 不包括侧边栏. 默认为 False .

  • sidebarwidth (int或str): 侧边栏的宽度(以像素为单位). 这可以是 int, 它被解释为像素或有效的CSS维度字符串, 例如 ‘70em’ 或 ‘50％’. 默认为230像素.

  • body_min_width (int或str):文档正文的最小宽度. 这可以是int, 它被解释为像素或有效的CSS维度字符串, 例如‘70em’或‘50％’. 如果您不想要宽度限制, 请使用0. 默认值可能取决于主题(通常为450px).

  • body_max_width (int或str):文档正文的最大宽度. 这可以是int, 它被解释为像素或有效的CSS维度字符串, 例如‘70em’或‘50％’. 如果您不想要宽度限制, 请使用 none . 默认值可能取决于主题(通常为800px).

alabaster

Alabaster theme 是来自@kennethreitz的修改后的 Kr Sphinx主题(特别是在他的Requests项目中使用), 它本身最初基于@mitsuhiko用于Flask及相关项目的主题. 有关如何配置的信息, 请参阅其 installation page html_sidebars 供其使用.

classic

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

  • 右侧栏 (true or false):将侧边栏放在右侧. 默认为 False .

  • stickysidebar (true or false):使侧边栏 固定 , 以便它不会滚出视图以获取长身体内容. 这可能不适用于所有浏览器. 默认为 False .

  • collapsiblesidebar (true or false):添加一个*实验性* JavaScript代码段, 通过侧面的按钮使侧边栏可折叠. 默认为 False .

  • externalrefs (true或false):显示外部链接与内部链接不同. 默认为 False .

还有各种颜色和字体选项可以更改颜色方案, 而无需编写自定义样式表:

  • footerbgcolor (CSS颜色):页脚行的背景颜色.

  • footertextcolor (CSS颜色):页脚行的文本颜色.

  • sidebarbgcolor (CSS颜色):侧边栏的背景颜色.

  • sidebarbtncolor （CSS颜色:侧边栏折叠按钮的背景颜色（当 collapsiblesidebar 为 True 时使用）。

  • sidebartextcolor (CSS颜色):侧边栏的文本颜色.

  • sidebarlinkcolor (CSS颜色):侧边栏的链接颜色.

  • relbarbgcolor (CSS颜色):关系栏的背景颜色.

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

  • relbarlinkcolor (CSS颜色):关系栏的链接颜色.

  • bgcolor (CSS颜色):身体背景颜色.

  • textcolor (CSS颜色):正文文本颜色.

  • linkcolor (CSS颜色):正文链接颜色.

  • visitedlinkcolor (CSS颜色):访问过的链接的正文颜色.

  • headbgcolor (CSS颜色):标题的背景颜色.

  • headtextcolor (CSS颜色):标题的文本颜色.

  • headlinkcolor (CSS颜色):标题的链接颜色.

  • codebgcolor (CSS颜色):代码块的背景颜色.

  • codetextcolor (CSS颜色): 代码块的默认文本颜色，如果没有通过突出显示样式设置不同.

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

  • headfont (CSS字体系列):标题的字体.

sphinxdoc

本文档最初使用的主题。它的右侧有一个侧边栏。除了* nosidebar 和 sidebarwidth *之外，目前没有其他选项。

注解

Sphinx文档现在使用了 sphinxdoc主题的调整版本。

scrolls

一个更轻量级的主题, 基于 Jinja文档. 可以使用以下颜色选项:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

Andi Albrecht创作的主题. 支持以下选项:

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

  • headerfont (CSS字体系列):标题字体.

  • pagewidth (CSS长度):页面内容的宽度, 默认为70em.

  • documentwidth (CSS长度):文档的宽度(没有侧边栏), 默认为50em.

  • sidebarwidth (CSS长度):侧边栏的宽度, 默认为20em.

  • bgcolor (CSS color): 背景颜色.

  • headerbg (“background” 的CSS值):标题区域的背景, 默认为浅灰色渐变.

  • footerbg (“background” 的CSS值):页脚区域的背景, 默认为浅灰色渐变.

  • linkcolor (CSS颜色):正文链接颜色.

  • headercolor1, headercolor2 (CSS颜色):<h1>和<h2>标题的颜色.

  • headerlinkcolor (CSS颜色):标题中后向引用链接的颜色.

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

nature

一个绿色的主题. 除了 nosidebar 和 sidebarwidth 之外, 目前没有其他选项.

pyramid

由Blaise Laflamme设计的金字塔网络框架项目的主题. 除了 nosidebar 和 sidebarwidth 之外, 目前没有其他选项.

haiku

没有侧栏的主题受到了 Haiku OS用户指南 的启发. 支持以下选项:

  • full_logo (true 或 false, 默认为 False):如果这是真的, 标题只会显示 html_logo. 用于大型徽标. 如果这是假的, 则徽标(如果存在)将浮动右侧显示, 文档标题将放在标题中.

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS颜色):各种身体元素的颜色.

traditional

一个类似于旧Python文档的主题. 除了 nosidebar 和 sidebarwidth 之外, 目前没有其他选项.

epub

epub构建器的主题. 这个主题试图保留视觉空间, 这是电子书阅读器上的稀疏资源. 支持以下选项:

  • relbar1 (true 或 false, 默认为 True): 如果为true, 则将 relbar1 块插入epub输出中, 否则将省略.

  • footer (true 或 false, 默认为 True):如果为true, 则在脚本输出中插入 footer 块, 否则省略.

bizstyle

一个简单的蓝色主题. 除了 nosidebar 和 sidebarwidth 之外, 还支持以下选项:

  • 右侧栏 (true or false):将侧边栏放在右侧. 默认为 False .

1.3 新版功能: ‘alabaster’, ‘sphinx_rtd_theme’ 和 ‘bizstyle’ 主题. ``

在 1.3 版更改: ‘default’ 主题已重命名为 ‘classic’. ‘default’ 仍然可用, 但它会发出通知, 告知它是新 ‘alabaster’ 主题的别名.

第三方主题

主题概述

sphinx_rtd_theme

sphinx_rtd_theme

有许多第三方主题可用. 其中一些是一般用途, 而另一些则是针对单个项目的. 下面列出了第三方主题的一部分. 在 PyPI, GitHub 和 sphinx-themes.org 上可以找到更多.

sphinx_rtd_theme

Read the Docs Sphinx Theme. 这是一个针对readthedocs.org制作的适合移动设备的sphinx主题. 在readthedocs.org上查看工作演示. 您可以在 Read the Docs Sphinx Theme 页面获取安装和选项信息.

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