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
fonts. There is also a
bower.json and a
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 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.
script_files array to the page and completes the process by including its own
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
Navigation and search
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.
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.
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