HTML 主题化

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

构建器

待处理

当 “构建器” 文档被拆分时进行填充。

主题

0.6 新版功能.

注解

本节提供关于使用预先存在的 HTML 主题的信息。如果你想创建你自己的主题，请参考 HTML 主题开发。

Sphinx 支持通过 主题 改变其 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

一旦安装，就可以用与目录或基于 zip 文件的主题相同的方式使用

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 comes with a selection of themes to choose from.

These themes are:

basic

This is a basically unstyled layout used as the base for the other themes, and usable as the base for custom themes as well. The HTML contains all important elements like sidebar and relation bar. There are these options (which are inherited by the other themes):

  • nosidebar (true or false): Don’t include the sidebar. Defaults to False.

  • sidebarwidth (int or str): Width of the sidebar in pixels. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Defaults to 230 pixels.

  • body_min_width (int or str): Minimal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Use 0 if you don’t want a width limit. Defaults may depend on the theme (often 450px).

  • body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’ if you don’t want a width limit. Defaults may depend on the theme (often 800px).

  • navigation_with_keys (true or false): Allow navigating to the previous/next page using the keyboard’s left and right arrows. Defaults to False.

  • globaltoc_collapse (true or false): Only expand subsections of the current document in globaltoc.html (see html_sidebars). Defaults to True.

    3.1 新版功能.

  • globaltoc_includehidden (true or false): Show even those subsections in globaltoc.html (see html_sidebars) which have been included with the :hidden: flag of the toctree directive. Defaults to False.

    3.1 新版功能.

  • globaltoc_maxdepth (int): The maximum depth of the toctree in globaltoc.html (see html_sidebars). Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive.

    3.2 新版功能.

alabaster

Alabaster theme is a modified “Kr” Sphinx theme from @kennethreitz (especially as used in his Requests project), which was itself originally based on @mitsuhiko’s theme used for Flask & related projects. Refer to its installation page for information on how to configure html_sidebars for its use.

classic

This is the classic theme, which looks like the Python 2 documentation. It can be customized via these options:

  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to False.

  • stickysidebar (true or false): Make the sidebar “fixed” so that it doesn’t scroll out of view for long body content. This may not work well with all browsers. Defaults to False.

  • collapsiblesidebar (true or false): Add an experimental JavaScript snippet that makes the sidebar collapsible via a button on its side. Defaults to False.

  • externalrefs (true or false): Display external links differently from internal links. Defaults to False.

There are also various color and font options that can change the color scheme without having to write a custom stylesheet:

  • footerbgcolor (CSS color): Background color for the footer line.

  • footertextcolor (CSS color): Text color for the footer line.

  • sidebarbgcolor (CSS color): Background color for the sidebar.

  • sidebarbtncolor (CSS color): Background color for the sidebar collapse button (used when collapsiblesidebar is True).

  • sidebartextcolor (CSS color): Text color for the sidebar.

  • sidebarlinkcolor (CSS color): Link color for the sidebar.

  • relbarbgcolor (CSS color): Background color for the relation bar.

  • relbartextcolor (CSS color): Text color for the relation bar.

  • relbarlinkcolor (CSS color): Link color for the relation bar.

  • bgcolor (CSS color): Body background color.

  • textcolor (CSS color): Body text color.

  • linkcolor (CSS color): Body link color.

  • visitedlinkcolor (CSS color): Body color for visited links.

  • headbgcolor (CSS color): Background color for headings.

  • headtextcolor (CSS color): Text color for headings.

  • headlinkcolor (CSS color): Link color for headings.

  • codebgcolor (CSS color): Background color for code blocks.

  • codetextcolor (CSS color): Default text color for code blocks, if not set differently by the highlighting style.

  • bodyfont (CSS font-family): Font for normal text.

  • headfont (CSS font-family): Font for headings.

sphinxdoc

The theme originally used by this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar and sidebarwidth.

注解

The Sphinx documentation now uses an adjusted version of the sphinxdoc theme.

scrolls

A more lightweight theme, based on the Jinja documentation. The following color options are available:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

A theme created by Andi Albrecht. The following options are supported:

  • bodyfont (CSS font family): Font for normal text.

  • headerfont (CSS font family): Font for headings.

  • pagewidth (CSS length): Width of the page content, default 70em.

  • documentwidth (CSS length): Width of the document (without sidebar), default 50em.

  • sidebarwidth (CSS length): Width of the sidebar, default 20em.

  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to True.

  • bgcolor (CSS color): Background color.

  • headerbg (CSS value for “background”): background for the header area, default a grayish gradient.

  • footerbg (CSS value for “background”): background for the footer area, default a light gray gradient.

  • linkcolor (CSS color): Body link color.

  • headercolor1, headercolor2 (CSS color): colors for <h1> and <h2> headings.

  • headerlinkcolor (CSS color): Color for the backreference link in headings.

  • textalign (CSS text-align value): Text alignment for the body, default is justify.

nature

A greenish theme. There are currently no options beyond nosidebar and sidebarwidth.

pyramid

A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond nosidebar and sidebarwidth.

haiku

A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:

  • full_logo (true or false, default False): If this is true, the header will only show the html_logo. Use this for large logos. If this is false, the logo (if present) will be shown floating right, and the documentation title will be put in the header.

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): Colors for various body elements.

traditional

A theme resembling the old Python documentation. There are currently no options beyond nosidebar and sidebarwidth.

epub

A theme for the epub builder. This theme tries to save visual space which is a sparse resource on ebook readers. The following options are supported:

  • relbar1 (true or false, default True): If this is true, the relbar1 block is inserted in the epub output, otherwise it is omitted.

  • footer (true or false, default True): If this is true, the footer block is inserted in the epub output, otherwise it is omitted.

bizstyle

A simple bluish theme. The following options are supported beyond nosidebar and sidebarwidth:

  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to False.

1.3 新版功能: ‘alabaster’, ‘sphinx_rtd_theme’ and ‘bizstyle’ theme.

在 1.3 版更改: The ‘default’ theme has been renamed to ‘classic’. ‘default’ is still available, however it will emit a notice that it is an alias for the new ‘alabaster’ theme.

三方主题

有许多第三方主题可用于 Sphinx。其中一些是通用的，而另一些是针对个别项目的。

sphinx-themes.org 是一个画廊，展示了 Sphinx 的各种主题，每个主题下都有演示文档呈现。主题也可以在 PyPI （使用分类器 Framework :: Sphinx :: Theme）、GitHub 和 GitLab 找到。