【问题标题】：Customize sphinxdoc theme自定义 sphinxdoc 主题
【发布时间】：2013-01-15 08:56:08
【问题描述】：

有没有一种简单的方法来自定义现有的sphinxdoc 主题？对于默认主题，有很多主题属性，但在 sphinxdoc 中我什至无法设置徽标或更改某些颜色。

或者你能推荐一个我可以学习如何修改主题的网站吗？

【问题讨论】：

【解决方案1】：

我只想在我的 sphinx 文档中添加 ReST strikethrough。这是我的做法：

$ cd my-sphinx-dir
$ mkdir -p theme/static
$ touch theme/theme.conf
$ touch theme/static/style.css

在theme/theme.conf:

[theme]
inherit = default
stylesheet = style.css
pygments_style = pygments.css

（这使它看起来像默认主题（l.2））

在theme/static/style.css:

@import url("default.css"); /* make sure to sync this with the base theme's css filename */

.strike {
    text-decoration: line-through;
}

然后，在你的 conf.py 中：

html_theme = 'theme' # use the theme in subdir 'theme'
html_theme_path = ['.'] # make sphinx search for themes in current dir

（可选）在 global.rst 中：

.. role:: strike
   :class: strike

在 example.rst 中：

.. include:: global.rst

:strike:`This looks like it is outdated.`

【讨论】：

【解决方案2】：

为了自定义现有的sphinxdoc 主题，您需要创建包含所需修改的自定义模板和样式表。

`_template` 和 `_static` 子文件夹

在您的 sphinx 文档文件夹（本例中名为 docs）中，创建两个子文件夹：_static 和 _templates：

docs
├── conf.py
├── index.rst
└── _templates
    └── page.html
└── _static
    └── style.css

`style.css` 样式表

在_static 文件夹中，创建一个文件style.css，其中包含您要覆盖的CSS 选项。您可以通过查看 sphinx 安装文件夹中的 sphinxdoc 主题样式表找到适用的选项：

./python3.4/site-packages/Sphinx-1.3.1-py3.4.egg/sphinx/themes/sphinxdoc/static/sphinxdoc.css_t`

要将文档背景从白色更改为黑色，请将以下几行添加到style.css：

body {
    background-color: black;
    color: white;
}
div.document {
    background-color: black;
}

要使用.. rst-class:: centered 指令添加使代码居中的功能，请添加以下行：

.centered {
    text-align: center;
}

等等……

在_templates 子文件夹中，创建一个文件page.html，其内容如下：

{% extends "!page.html" %}

{% set css_files = css_files + ["_static/style.css"] %}

这告诉 sphinx 在 _static 文件夹中查找 style.css 样式表。

这些说明来自 Tinkerer 关于主题的文档：http://tinkerer.me/doc/theming.html。 Tinkerer 是一个基于 Sphinx 的博客引擎。

【讨论】：

【解决方案3】：

除非我误解了你，否则standard Sphinx documentation 会告诉你如何修改现有主题和创建新主题。

我实际上安装了 Sphinx cloud theme，然后开始编辑它的模板；所以我有了一个新主题，我可以准确地看到需要什么，但我不需要从头开始创建。

如果您想更改 CSS 布局，可以将 CSS 文件（或图像）添加到您的 source 的 _static 子目录中，并根据需要编辑您的 conf.py。同样，云主题是我最好的例子。

【讨论】：

【解决方案4】：

对于 Sphinx 1.8.2，默认主题是 Alabaster，我通过添加配置了 html_style 的新样式表来自定义它：

conf.py:

html_style = 'custom.css'

_static/custom.css:

@import url("alabaster.css");

blockquote{
  background: white;
  color: black;
  display: block;
}

【讨论】：