自定义sphinxdoc主题

Question

有没有简单的方法可以自定义现有的 sphinxdoc 主题？对于默认主题，有很多主题属性可以调整，但在 sphinxdoc 中，我连 logo 都无法设置，颜色也不能更改。

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

Answer 1

如果我没有理解错的话，标准的Sphinx文档会告诉你怎么修改现有的主题和创建新的主题。

我其实安装了Sphinx的云主题，然后开始编辑它的模板；这样我就有了一个新的主题，可以清楚地看到需要做什么，而不需要从头开始创建。

如果你想改变CSS的布局，可以把CSS文件（或者图片）放到你的source文件夹里的_static子文件夹中，然后根据需要编辑你的conf.py文件。再次强调，云主题是我最好的例子。

Answer 2

为了自定义现有的 sphinxdoc 主题，你需要创建一个自定义的模板和样式表，里面包含你想要的修改。

---

_templates 和 _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;
}

等等...

---

page.html 模板

在 _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 的博客引擎。

另外，可以查看：如何将自定义 CSS 文件添加到 Sphinx？。

Answer 3

我想在我的sphinx文档中添加一个叫做ReST删除线的效果。下面是我怎么做到的：

$ 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

（这样做会让它看起来像默认主题（第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

更多信息可以查看这里：https://sphinx.readthedocs.io/en/master/theming.html。

（可选）在global.rst文件中：

.. role:: strike
   :class: strike

还有在example.rst文件中：

.. include:: global.rst

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