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?
Answers:
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.
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.`
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?.
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;
}
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?
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.
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.`
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?.
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;
}