自定义 sphinxdoc 主题

Posted 2023-02-19

【中文标题】自定义 sphinxdoc 主题

【英文标题】：Customize sphinxdoc theme

【发布时间】：2013-01-15 08:56:08

【问题描述】：

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

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

【问题讨论】：

docs.readthedocs.io/en/stable/guides/…

【参考方案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

更多信息：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.`

【参考方案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;

等等……

---

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

另外，请参阅：How to add a custom css file?。

【参考方案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;

【讨论】：

我觉得文件也可以命名为_static/custom.css_t