A tour of the Read the Docs Sphinx theme

Today I want to take you on a tour of the Read the Docs theme for Sphinx. We'll look into what goes into it and then look at what web technologies are being used to make this theme happen. In a different take from the theme's own documentation, our journey will take us through the internals of the theme, not its use.

The Read the Docs theme is a good starting point for looking into the anatomy of custom Sphinx themes. It is widely used and has a large feature set. Additionally it is permissively licensed free software, so you can go ahead and base customizations on it.

Have a look at the top-level folder of the theme here https://github.com/rtfd/sphinx_rtd_theme You'll find the top-level folders sass, js, and fonts. There is also a bower.json and a Gruntfile.js.

The build process

Sphinx themes are mostly static assets, but to get to that state the RTD theme will compile the basic elements from a set of inputs. Bower (https://bower.io/) is used to pull the requirements for the build process into the build environment. After this is complete, you will call Grunt (https://gruntjs.com/) to run the build process.

The primary part of the Grunt build consists of running the SASS CSS pre-processor to compile the SASS templates into proper CSS. After this is done, JavaScript and CSS get some polish so they'll be more easily delivered to users. Then static files like fonts are copied into place and off we go. After the build process is finished, you will have an install-ready Sphinx theme.

The core templates

The core of the theme is formed by a set of Jinja template files. These files live in a Python package, in the same way the Sphinx theming documentation recommends (http://www.sphinx-doc.org/en/master/theming.html). When the package's setup function gets called, it will add its own directory to the list of template directories.

Of the templates you'll find in the sphinx_rtd_theme folder, only layout.html (yes this is a template) is a full fledged template in the sense that it can render a complete HTML page. This file includes a DOCTYPE declaration to indicate that this is HTML5.

The basic page template has to include all the required JavaScript. It does this, by including Modernizr (https://modernizr.com/) which is used to detect browser features. It then adds all the elements of the script_files array to the page and completes the process by including its own theme.js.

To complete the prerequisites for page rendering, template.html adds its own CSS file to the header and continues with the vanilla Pygments CSS (http://pygments.org/), finishing up with any files that were put into extra_css_files.

The theme has three main navigation aids. There is the well known Sphinx toctree that gets rendered into every page. There are the breadcrumbs in breadcrumbs.html, which provide a way for the user to visualize their position in the document collection and a way to jump to central points. And finally there is the footer which provides "next" and "previous" buttons.

Search in Sphinx is a bit special, because it is implemented on the client-side of the browser. The RTD theme has support for this feature of Sphinx, and it also customizes the feature in a visual way.

The CSS code

One of the major parts of the theme (at least by lines of code) is the CSS set of rules that lead to a nice looking page.

The major entry point into the theme is theme.sass, which then ties all the other files in this directory together and also includes external definitions.

The SASS definitions use Wyrm (http://wyrmsass.org/) for a lot of boilerplate functionality as well as Neat (https://neat.bourbon.io/) to create a base grid. Additionally FontAwesome is used to clue in the user with icons.

In addition to supporting the features the theme brings to the table (like breadcrumbs), it will style MathJax code. But the core of the RST element formatting resides in _theme_rst.sass, which has all the details on how to handle the different RST markup elements.

Testing

Finally there are some tests for this theme. These are real tests, they can run automatically, and can serve as a kind of smoke-test, to alert when something is seriously wrong with the theme.

The test are located in tests in the file test_builders.py. They will essentially render a documentation project and then do some sanity checks on the HTML output.

Summary

The Sphinx has a big feature set and is a good candidate for basing your own themes on. This theme is heavy on JavaScript and modern web frameworks. In my opinion it could be a little bit more Python oriented, but you can avoid JavaScript only for so long if you want to produce a modern looking web page as the output.

This post serves a bit as a personal memory aid, and a nudge to get familiar with some front-end technologies, which I have been avoiding in the past.

Title image: Labyrinth 28, etching, aquatint, soft-ground etching, mm.180x330, Engraved and designed by Toni Pecoraro 2007. http://www.tonipecoraro.it/labyrinth28.html