自定义sphinxdoc主题

Question

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

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

Answer 1

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

(这使它看起来像默认主题(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

在一个例子中:

.. 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文件夹中,创建一个style.css包含要覆盖的CSS选项的文件.您可以通过查看sphinxdocsphinx安装文件夹中的主题样式表找到适用的选项:

./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文件夹中查找样式表.