Note

本文翻译自 Sphinx 官网教程 翻译于2017-06-02

Sphinx 主题的使用与修改

Sphinx 支持通过 主题 themes 来改变它的HTML的输出。

在Sphinx中,主题是指一组 HTML templates、css以及javascript等静态文件。 除此之外,它还含有一个配置文件指出它继承哪个主题,使用哪个代码高亮的配置, 及暴露了那些配置项用于确定最终的输出。

themes 的设计意图是与具体的项目分离,也就是说一个主题可以在不做任何修改的情况下用于任何项目。

主题的使用

使用一个主题非常简单。

对于使用Sphinx内置的主题,你只需要设置 conf.py 配置文件中的 html_theme 选项的值。并且通过设置 html_theme_options 的值,你可以对这个主题支持 的一些选项进行设置,从而将HTML的输出按照你的需求进行修改。例如,你可以在你的 conf.py 文件中这样配置:

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

上述的配置代表你使用classic主题,并且将边栏设置于右边,同时将 关联栏 relation bar 的背景调整为黑色(此处的relation bar是指HTML头部和尾部的有next,brevious的链接的部分)。

使用非Sphinx内置的主题,有三种方法:第一种是项目内的一个文件夹,里面包含了 theme.conf 文件和其他必要的如 template 之类的文件,或者直接是这个文件夹的zip压缩包;第二种是将 主题放在任何一个Sphinx可以找到的地方,对于这种方法,你需要在 conf.py 文件 中设置 html_theme_path 选项,在这个文件夹中,可以放置一系列的主题。例如,你可以在 /opt/sphinx_themes 文件夹中放一个 blue.zip 文件,然后在 conf.py 中这样设置:

html_theme = "blue"
html_theme_path = ["/opt/sphinx_themes"]

第三种方法是使用一个发布的第三方python包,(例如sphinxjp.themes.dotted), 你可以在安装这个python package后直接使用它。

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

# use it in your conf.py
html_theme = "dotted"

内置主题

主题预览  

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

Sphinx 内置了一系列主题供选择:

  • basic – 这是基本的Sphinx主题,没有样式。通常这个主题适用于被其他主题 继承的。这个主题包含了所有主要的组件,如 sidebarrelation bar 。 它有这些属性,并且这些属性通常也被其他属性所继承:

    • nosidebar (true or false): 是否包含侧边栏。默认值是 False
    • sidebarwidth (整数): sidebar 的宽度的像素值。默认值是230。
  • alabasterAlabaster 主题 是一个由@kennethreitz开发的主题,这在他自己的 Requests 项目中也被用到了。这个主题的详细配置可以参考 安装页面

  • classic – 这是一个传统的主题,看起来非常像 Python 2 官方文档 这个主题可以通过这些选项来设置:

    • rightsidebar (true or false): 将边栏放置于右边,默认为 False
    • stickysidebar (true or false): 修正边栏使得边栏不会在滚动时滚出屏幕。 这个设置可能在小部分浏览器上无效。此项的默认值为 False
    • collapsiblesidebar (true or false): 一个 实验性 的JavaScript脚本, 这个脚本会使得边栏可以通过一个在它边上的按钮折叠。要注意,这个选项不能与 stickysidebar 同时使用。此项的默认值为 False
    • externalrefs (true or false): 使得外部链接的显示与站内链接的显示不同。 此项的默认值为 False

    同时这里也提供一些颜色和字体选项,用于在不用修改css样式表的情况下修改颜色。

    • footerbgcolor (CSS color): 页面最下一行的背景颜色。
    • footertextcolor (CSS color): 页面最下一行的文字颜色。
    • sidebarbgcolor (CSS color): 边栏的背景颜色。
    • sidebarbtncolor (CSS color): 边栏折叠按钮的颜色(只有当 collapsiblesidebar 选项开启的时候才有效)。
    • sidebartextcolor (CSS color): 边栏的文字颜色。
    • sidebarlinkcolor (CSS color): 边栏的链接的颜色。
    • relbarbgcolor (CSS color): 关联栏 Relation Bar 的背景颜色。
    • relbartextcolor (CSS color): 关联栏 Relation Bar 的文字颜色。
    • relbarlinkcolor (CSS color): 关联栏 Relation Bar 的链接的颜色。
    • 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 – Sphinx官方文档所采用的主题,这个主题的边栏在右边。目前这个主题中, 除去 nosidebarsidebarwidth 没有别的选项。

  • 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 (CSS value for “background”): 头部background区域设置,默认值是 a grayish gradient。
    • footerbg (CSS value for “background”): 尾部background区域设置,默认值是 a light gray gradient。
    • linkcolor (CSS color): 正文的链接的颜色。
    • headercolor1, headercolor2 (CSS color): <h1> 和 <h2> 标签的颜色。
    • headerlinkcolor (CSS color): 标题中的回调链接的颜色。
    • textalign (CSS text-align value): 正文的文本对齐方式。默认值是 justify
  • nature – 一个绿色的主题,目前为止,除了 nosidebarsidebarwidth 之外 没有别的选项。

  • pyramid – 这个主题来自Pyramid web框架,由Blaise Laflamme设计。除了 nosidebarsidebarwidth 之外 没有别的选项。

  • haiku – 这是一个没有边栏的主题,灵感来源于 Haiku OS user guide 。支持的选项如下:

    • full_logo (true or false, default False): 当这个选项开启时,文档的 头部只会包含 html_logo 。这个选项用于像素较大的logo。
    • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): 用于设置不同元素的颜色。
  • traditional – 这是一个类似于老板python文档的主题,除了 nosidebarsidebarwidth 之外 没有别的选项。

  • epub – 一个epub输出的主题,epub是通常电子书支持的格式。这个主题会尝试将 边栏中的目录存为电子书的目录。支持如下的选项:

    • relbar1 (true or false, default True): 将 relbar1 插入epub的输出。
    • footer (true or false, default True): 将 footer 插入epub的输出。
  • bizstyle – 这时一个蓝色的简单的主题,除了 nosidebarsidebarwidth 还支持如下选项:
    • rightsidebar (true or false): 将侧边栏放到右边。

新建自己的主题

之前的内容中提到,主题就是一个文件夹或者一个zip压缩包。通常主题包含如下内容:

  • 一个 theme.conf 文件,后面会详细介绍。
  • (可选)HTML模版文件,Sphinx的模版文件采用Jinja。
  • 一个 static/ 文件夹,其中包含了所有的将会在编译时被拷贝到编译文件夹的static文件夹内。 这个文件夹中可以包含图片,样式表,JS文件。

theme.conf 文件是一个INI格式的配置文件,由python标准模块 ConfigParser 读取。它有如下的结构:

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

[options]
variable = default value
  • inherit 用于选择你的主题继承于哪个主题。当你的主题缺失某个HTML模版时,会使用你 继承的主题中的这个模版。大多数主题会继承 basic 主题,并且不会给出所有的模版。
  • stylesheet 指定了会在HTML头中申明的css样式表文件名称。如果你需要多个样式表文件, 你既可以使用CSS的 @import 属性,也可以在HTML模版中加入 <link rel="stylesheet"> 标签。注意,在配置文件中使用 html_style 设置将会覆盖此项设置。
  • pygments_style 设置你使用的Pygments代码高亮插件。这一项可以被配置文件中的 pygments_style 项覆盖。
  • options 这里面的每一行都是一个参数以及它的默认值,这一项可以被配置文件中的 html_theme_options 重写。

将你的主题打包成python包发布

将你的主题打包发布的一种方式就是大包成python的包。打包Python包的方法非常简单。

为了将你的主题打包成python包,请在 setup.py 文件中将入口设置为 sphinx.html_themes ,并且编写 setup() 函数,使用 add_html_theme() API 来注册你的主题:

# 'setup.py'
setup(
    ...
    entry_points = {
        'sphinx.html_themes': [
            'name_of_theme = your_package',
        ]
    },
    ...
)

# 'your_package.py'
from os import path

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

如果你的主题包中包含两个以上的主题,可以多次使用 add_html_theme() 函数。

HTML模版

如果你想写自己的主题模版,推荐你看 Template指南 <http://www.sphinx-doc.org/en/stable/templating.html> 需要注意的是Sphinx查找Template的顺序:

  • 首先,在你的 templates_path 文件夹。
  • 其次,在你选择的主题中查找。
  • 最后,按照继承关系查找你使用的主题继承的主题。

当你扩展一个你使用的主题的模版时,在你的模版中引用主题的模版 {% extends "basic/layout.html" %} 。在一个用户的 templates_path 模版中,你也可以使用Template文档中介绍过的”感叹标记”。

静态模版

尽管主题的选项意在使得用户可以通过不写样式表的情况下设置一个主题。Sphinx也支持 静态模版文件和HTML文件,也就是Sphinx支持 “static template静态模版”,例如:

如果一个文件在 static/ 文件夹中,并且以 _t 结尾,这个文件就会被传递 给模版引擎。 _t 标志在最终的编译结果中不会出现。

第三方主题

主题预览  

sphinx_rtd_theme

sphinx_rtd_theme