Customize sphinxdoc theme

Question

Is there an easy way to customize the existing sphinxdoc theme? For the default theme, there are many theme-attributes, but in sphinxdoc I can't even set a logo or change some colors.

Or can you recommend me a site where I can learn how to modify themes?

Answer 1

All I wanted is to add ReST strikethrough in my sphinx doc. Here is how I did it:

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

In theme/theme.conf:

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

(this makes it look like the default theme (l. 2))

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

Then, in your conf.py:

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

More here: https://sphinx.readthedocs.io/en/master/theming.html.

(Optional) In global.rst:

.. role:: strike
   :class: strike

and in a example.rst:

.. include:: global.rst

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

Answer 2

In order to customize the existing sphinxdoc theme, you need to create a custom template and stylesheet that contains the desired modifications.

---

_templates and _static subfolders

In your sphinx documentation folder (named docs in this example), create two subfolders: _static and _templates:

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

---

style.css stylesheet

In the _static folder, create a file style.css containing CSS options that you wish to overwrite. You can find the applicable options by looking at the sphinxdoc theme stylesheet, inside the sphinx installation folder:

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

To change the document background from white to black, add the following lines to style.css:

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

To add the ability to center your code using the .. rst-class:: centered directive, add the following lines:

.centered {
    text-align: center;
}

etc...

---

page.html template

In the _templates subfolder, create a file page.html with the following content:

{% extends "!page.html" %}

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

This tells sphinx to look for the style.css stylesheet in the _static folder.

---

More information

These instructions are from the Tinkerer documentation on theming: http://tinkerer.me/doc/theming.html. Tinkerer is a blogging engine based on Sphinx.

Also, see: How to add custom css file to Sphinx?.

Answer 3

Unless I misunderstand you, the standard Sphinx documentation tells you how to modify existing and create new themes.

I actually installed the Sphinx cloud theme, and then started editing its templates; so I had a new theme where I could see exactly what is required, but that I didn't need to create from scratch.

If you want to alter the CSS layout, you can add CSS files (or images) into the _static subdirectory of your source, and edit your conf.py as necessary. Again, the cloud theme was my best example for that.

Answer 4

For Sphinx 1.8.2 the default theme is Alabaster which I customize by adding a new stylesheet configured with html_style:

conf.py:

html_style = 'custom.css'

_static/custom.css:

@import url("alabaster.css");

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