| Abstract: | Notes on Sphinx Themes and customization |
|---|---|
| Author: | Thava Alagu |
| Date: | 25 Jan 2013 |
Contents
Sphinx document generation tool was originally created for Python documentation. However it has grown to be very powerful general purpose documentation system based on RestructuredText.
Sphinx Theming is highly customizable. This document describes the resources and procedures about how to get and customize these themes.
I use this extensively to consolidate my own technical notes written using RestructuredText. Sphinx generates a nice consolidated documentation to view them.
You may want to look at Sphinx example site customization Tutorial first for an example.
Basically this involves following steps:
Run sphinx-quickstart to generate a build template.
Change index.rst file to include yourfile.rst
Customize the following files:
$ ls _static/ _templates/
_static/:
basic_screenshot.png default.css logo.png
_templates/:
layout.html
This gives some fundamental ideas about customization. All these above changes are applied on top of the basic built-in theme that is in effect. You can change that theme too if you like.
To see the list of built-in themes available, look inside your Python installation:
$ ls lib/python2.7/*-packages/sphinx/themes/
agogo/ basic/ default/ epub/ haiku/ nature/ pyramid/
scrolls/ sphinxdoc/ traditional/
See Sphinx Theming to preview their look and feel. Built-in themes come with certain amount of customization options. You can specify following in your conf.py file as an example:
html_theme = "default"
html_theme_options = {
"rightsidebar": "true",
"stickysidebar": "true",
"relbarbgcolor": "black"
}
If this is more than what you need, you can stop here. If you want further customization, read on.
Go to Python Package Index and search for Sphinx theme or Sphinx template. Here are some of the themes I chose to install from that list:
$ themes=" sphinxjp.themes.basicstrap
sphinxjp.themes.bizstyle
sphinxjp.themes.dotted
sphinxjp.themes.htmlslide
sphinxjp.themes.impressjs
sphinxjp.themes.s6
sphinxjp.themes.trstyle
"
$ pip install $themes
To preview these themes, usually you just configure your conf.py, like below
# basicstrap / bizstyle / dotted / htmlslide / impressjs / s6 / trstyle
html_theme=basicstrap
html_theme_options = {}
$ make html
Refer to the theme specific documentation from Python Package Index package page for more information.
It is very handy to be able to generate presentation slides by writing RestructuredText text. There are few such extensions among the earlier mentioned sphinxjp.* themes:
The impressjs support is very impressive. You can look at the impressjs sphinx extension demo page. The source for the above demo is here
After comparing many themes, I found the default theme is the best after tweaking for my taste: I enabled the rightsidebar instead of left. The next best built-in theme I liked is Pyramid with clean look. Next, among sphinxjp themes I liked bizstyle theme for general use. However, these are very subjective to one’s tastes.
There are also numerous other Sphinx themes– every major project such as django provides it’s own customized theme. It is easy to get inspiration by looking at some of them and just pick something you like as the base and customize it further if needed.
Often, by tweaking some options (like just increasing the fontsize), you can achieve dramatic improvements to suit your taste.
This document has been written using RestructuredText and converted to HTML using rst2html command.
See the document source text