更多信息

Question

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

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

Answer 1

我想要的只是在我的sphinx doc中添加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.`

Answer 2

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

`_template`和`_static`子文件夹

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

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

在_static文件夹中，创建一个包含您要覆盖的CSS选项的文件style.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在style.css文件夹中查找_static样式表。

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

Answer 3

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

我实际安装了Sphinx cloud theme，然后开始编辑其模板;所以我有一个新的主题，我可以看到确切的要求，但我不需要从头开始创作。

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

Answer 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;
}