用户自定义主题

11.3. 用户自定义主题#

Sphinx里面的模板是已经定义好了的，如果想要自定义主题，如修改主题的颜色、为主题增添内容等，那我们需要掌握一定的 jinja2、HTML 与 CSS知识。

11.3.1. 基础知识#

HTML#

超文本标记语言（英语：HyperText Markup Language，简称：HTML）是一种用于创建网页的标准标记语言。

同学们可以使用 HTML 来建立自己的 WEB 站点，HTML 运行在浏览器上，由浏览器来解析。

代码示例#

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>菜鸟教程(runoob.com)</title>
</head>
<body>
<h1>我的第一个标题</h1>
<p>我的第一个段落。</p>
</body>
</html>

代码解释#

  • <!DOCTYPE html> 声明为HTML5文档

  • <html> 是 HTML 页面的根元素

  • <head> 元素包含了文档的元数据，如 <meta charset="utf-8">表示网页编码格式为 utf-8

  • <title> 描述了文档的标题

  • <body> 包含了可见的页面内容

  • <h1> 定义一级标题

  • <p> 定义一个段落

推荐学习#

网上有很多免费的 HTML 教程，推荐如下：

CSS#

CSS 用于控制网页的样式和布局。

示例#

body
{
background-color:red;
}
h1
{
color:orange;
text-align:center;
}
p
{
font-family:"Times New Roman";
font-size:20px;
}

代码解释#

body
   {
   background-color:#d0e4fe;
   }

这段代码表示网页主题的背景色为红色。

h1
   {
   color:orange;
   text-align:center;
   }

这段代码表示标题1字体颜色为橘色，居中显示。

p
    {
    font-family:"Times New Roman";
    font-size:20px;
    }

这段代码表示段落文字的字体为 Times New Roman，字体大小为 20px。

推荐学习#

网上有很多免费的 CSS 教程，推荐如下：

jinja2#

如想对主题增添内容，那我们需要使用 jinja2 语言， jinja2 是 Flask 作者开发的一个模板系统，起初是仿 django 模板的一个模板引擎，为 Flask 提供模板支持，由于其灵活，快速和安全等优点被广泛使用。

Jinja 模版是一个文本文件，通过它可以生成任何文本格式的文件，例如 .html、.xml、.csv 等等。一个 Jinja 模版并不需要有一个特定的扩展名，完全可以自定义或是不定义.

Jinja 模版包含了变量、表达式和标签，当模版被渲染时，变量和表达式会被替换为特定的值，标签用来控制模版的逻辑。

代码示例#

<!DOCTYPE html>
<html lang="en">
<head>
<title>My Webpage</title>
</head>
<body>
<ul id="navigation">
{% for item in navigation %}
     <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
{% endfor %}
</ul>

<h1>My Webpage</h1>
{{ a_variable }}

{# a comment #}
</body>
</html>

代码解释#

  • {% ... %} 表示循环结构

  • {{...}} 里内含变量，需要对其进行赋值

  • {#...#} 用于注释，方便理解代码，并不会输出到结果文件中

  • {% endfor %} 表示循环体的结束

  • {{ item.href }} 表示访问 item 这个变量的 href 属性

推荐学习#

网上有很多免费的 HTML 教程，推荐如下：

11.3.2. 自定义主题实操#

要自定义文档的输出，可以通过将与原始文件名同名的文件添加到模板目录中来覆盖所有的模板。 Sphinx 将首先在 config.py 中的 template_path 和html_static_path 中查找模板，如果找不到它正在寻找的模板，将回退到所选主题的模板。

Sphinx安装目录下的 themes-basic 中包含 basic 主题，该主题中的 layout.html 为基本模板提供了几个块，这些块使用jinja2首先填充原始数据，并由所有内置的Sphinx主题使用。而 templates_path 中具有相同名称的模板会覆盖所选主题提供的模板。

该教程简单演示如何使用两种方法更改 Sphinx_rtd_theme 主题左侧导航栏的颜色。

安装jinja2#

Anaconda 环境中已经集成了 jinja2，因此无需再次安装。

查看需要修改的网页模块#

因为我们想要修改导航栏的颜色，所以需要知道生成的网页中左侧导航栏所对应的网页代码。

我们首先进入生成的网页，点击鼠标右键，进入检查，找到如下代码块：

nav-class
nav-class2

由以上代码块可知，导航栏所对应的模块属性为 wy-side-nav-search、 wy-nav-top、.wy-nav-side。因此，我们只需要对这几个属性进行修改即可。

方法一#

创建 同名模板 layout.html#

在文件夹里找到 source-templates 文件夹，然后在 templates 文件夹下创建 layout.html。

使用 jinja2 在 layout.html 中编写如下代码：

{% extends "!layout.html" %}
{% block footer %} {{ super() }}

<style>
/* Sidebar header (and topbar for mobile) */
.wy-side-nav-search, .wy-nav-top {
     background: green;
}
/* Sidebar */
.wy-nav-side {
     background: darkorange;
}
</style>
% endblock %}

对以上代码块解释如下：

  • {#...#} 相当于注释，是为了方便理解代码。

  • {% extends "!layout.html" %} 在带有感叹号的被覆盖模板的名称前面加上前缀，Sphinx将从底层HTML主题加载布局模板。

  • {% block footer %} 表示对 footer 代码块进行改写。

  • {{ super() }} 表示继承原模板，即呈现块的原始内容。

  • {% endblock %} 表示代码块结束。

此段代码的作用是在把网页头部导航栏背景色设置为绿色，左侧导航栏背景色设置为深橘色。

修改配置文件#

我们需要同步修改 config.py 中的配置：

templates_path = ['_templates']

生成网页#

点击保存后，重新在命令行中键入 make html，即可生成如下网页：

改变导航栏颜色

方法二#

该方法与方法一同理，只是把 css 文件单拎了出来, 即在 layout.html 中链接了外部的 css 文件，并将 css 文件置于static 文件夹下。

创建同名模板 layout.html#

编写代码如下：

{% extends "!layout.html" %}
{% block footer %} {{ super() }}

<link rel="stylesheet" type="text/css"
href="_static/custom.css">

% endblock %}

对以上代码块解释如下：

  • link rel="stylesheet"...custom.css 表示外链样式表。

创建 custom.css#

在文件夹里找到 source-static 文件夹，然后在 static 文件夹下创建 custom.css.

使用 css 语言 在 custom.css 中编写如下代码：

.wy-side-nav-search, .wy-nav-top
{
     background: green;
}
.wy-nav-side
{
     background: darkorange;
}

修改配置文件#

与此同时，在 config.py 中进行如下设置：

html_static_path = ["_static"]

templates_path = ['_templates']

生成网页#

点击保存后，重新在命令行中键入 make html，即可生成如下网页：

改变网页样式

单个网页主题修改#

经过以上操作步骤后，主页主题已修改完毕，但是当我们打开单个页面（如Chapter1）后，主题样式却并没有发生更改。如下图所示：

单个主题页面

原因为何呢？我们可以通过检查网页代码来找到答案。

在上图所示的页面点击鼠标右键，然后点击 检查 ，在控制台可以看到如下提示：

控制台错误

报错信息提示：找不到 css 文件的位置。将鼠标悬浮在报错信息上，出现如下路径地址：

路径地址

发现原来是 css 文件的地址出错了。为解决该问题，我们按照提示， 将 static 文件夹复制到 build-html-contents 文件夹下，保存后再次输入 make html，即可看到成功为子页面生成了主题。

路径地址

如果同学们想要改变网页的布局、字体信息等，都可以通过修改 custom.css 文件来实现。

目录