The Sizzle theme for Sphinx

The Sizzle theme for Sphinx

The Sizzle theme for Sphinx

This documentation describes Sizzle, a theme for Sphinx. This theme was inspired by another theme, Guzzle. Sizzle uses some of the styling elements of Guzzle, but has diverged a fair bit in numerous areas.

The repository where this theme is developed is to be found here.

Theme Options

Sizzle inherits from Sphinx’s basic theme. The following theme options are defined:

  • globaltoc_collapse – as for Guzzle: this determines whether the global TOC shown in the sidebar is collapsed or not. Defaults to false.
  • globaltoc_depth – as for Guzzle: the depth to which the global TOC is expanded. Defaults to 5.
  • globaltoc_includehidden – as for Guzzle: whether to include hidden entries in the global TOC. Defaults to true.
  • project_logo_name – this replaces Guzzle’s project_nav_name. The name change reflects that the value can be shown elsewhere than in a navigation panel.
  • sitemap_url – this replaces Guzzle’s base_url. The new name better reflects how the value is used - as a base URL for sitemap links.
  • google_fonts – this allows you to specify additional Google fonts to be included for use in any custom styles. Defaults to None.
  • google_analytics_id – this replaces Guzzle’s google_analytics_account. The name better reflects that the value is a tracker ID.
  • show_index – controls whether a link to the index is shown in the header. This defaults to true - set it to False to hide the link.
  • show_filter – controls whether a filter to apply to TOC titles is shown. This defaults to true - set it to False to hide the filter (which is not needed if you have a short enough list of entries in the TOC).
  • enable_tooltips – controls if tooltips are shown. This defaults to true - set it to False to disable tooltips.
  • glossary_permalinks – controls if glossary terms have permalinks. This defaults to true - set it to False to disable the permalinks.
  • custom_data – any custom data used by the theme. This defaults to an empty dictionary. This data needs to be loaded by JavaScript code in the HTML documentation, and so it should only contain content which is amenable to being serialized using JSON.

New in version 0.0.9: The custom_data theme element was added.


The layout has a scrolling area, consisting of sidebar and content, between a fixed header and footer. The footer is small (for copyright information and links) and the header has the following elements:

  • A gradient background
  • The project name (as determined by project_logo_name). Except when in the home page, you can click on this to get to the home page
  • The title of the current document
  • The search box, assuming the browser window is wide enough. If it isn’t, the search box relocates to the top of the sidebar.
  • A link to the index. This is conditionally visible (controlled by the show_index theme option) and styled as a button
  • A link to the source for the current page, if available. This is conditionally visible (controlled by the show_source option) and styled as a button
  • Links (styled as buttons) to take you to previous and next pages, if any

The sidebar and content area can scroll independently.


  • Font Awesome 4.7.0 is integrated. You can use the markup role fa to introduce a Font Awesome icon into your content. For example, the markup :fa:`diamond` produces in the finished output. You can append additional classes separated by commas, and they will be added to the icon. For example, :fa:`diamond,foo,bar` will have classes foo and bar added to the icon. You can inspect this in your browser:

  • Iconify Icons (open source) are integrated. You can use the markup role icon to introduce an SVG icon into your content. for example, the markup :icon:`octicon:git-branch-24` produces in the finished output. The icon name is composed of the icon set identifier and the icon identifier separated by a colon. After the icon name, you can append a height and additional CSS classes, all separated by commas. The height needs to be an integer or floating-point number immediately followed by an optional unit such as px, em, or rem (assumed to be px if omitted). Thus, :icon:`octicon:git-branch-24,1.25em,foo,bar` will produce in the output. You can easily include emojis – for example, the markup :icon:`noto:rolling-on-the-floor-laughing` will produce in the output.

    The produced icon element will have the iconify class added automatically.

    There are over 100,000 icons available - see the available icon sets. Sets include more recent Font Awesome, Octicons, Material Design, VS Code and many more.

    If the named icon isn’t found, an error will be raised.

  • Document and section titles use Source Serif Pro.

  • The default body font is Roboto, falling back to Guzzle’s slightly less compact choice of Open Sans.

  • The monospace font used for code blocks is Iosevka, which is a condensed font allowing more content to be shown than the fallbacks of Roboto Mono, Source Code Pro and Consolas. An example:

    @real fox.quick(h) { *is_brown && it_jumps_over(doges.lazy) }

New in version 0.1.0: Iconify icon support was introduced.

Google Fonts

If you want to use other Google fonts in your documentation, you can do this via a theme option:

html_theme_options = {
    # other stuff omitted
    'google_fonts': ['Acme', 'Raleway:400,700'],
    # other stuff omitted

This would make the Acme and Raleway fonts (the latter with the specific weights indicated) for use in your documentation, so that you could use Acme and Raleway in font-family values in your custom CSS.

Custom Roles

This theme adds two specific roles which you might find useful in documenting your projects:

  • The fa role, as described above.

  • A generic span role, which can be used as follows: the markup :span:`c1,c2,c3|some text` will result in the output

    <span class="c1 c2 c3">some text</span>

    This isn’t intended to be used to provide lots of ad-hoc styles (which would detract from the quality of the documentation), but it can be useful in some scenarios (such as trying things out). You can, of course, create your own roles in reStructuredText markup using the role directive

    .. role:: <rolename>

    This approach is preferable when your usage of a particular style is systematic rather than ad hoc.

    The sections on Summary-Detail Lists and Providing Customized Tooltips give examples where the span role can be useful.

Use of JavaScript, CSS and font assets

The version of jQuery used is 3.3.1. The version of Bootstrap used is 3.3.7. These are loaded from CDN, as are the fonts. No additional external assets beyond these are used, though you can add some in the usual way to a specific project – see the section Custom Styles and JavaScript for more details.

Styling Lists using Font Awesome

You can style bulleted lists using Font Awesome. For example, the following list:

  • Arcturus
  • Betelgeuse
  • VY Canis Majoris

was produced using this markup:

.. cssclass:: styled-list using-star

* Arcturus
* Betelgeuse
* VY Canis Majoris

A class starting with using- is used to style the list, with using- being replaced by fa- in the actual style applied.

You can override individual items with specific icons. For example,

  • Arcturus
  • Betelgeuse
  • VY Canis Majoris

was produced by this markup:

.. cssclass:: styled-list using-star

* :fa:`star-o` Arcturus
* :fa:`star-half-o` Betelgeuse
* VY Canis Majoris

Summary-Detail Lists

HTML5 has a handy feature - summary-detail lists, which are marked up like this:

  <summary>The summary goes here.</summary>
  <p>The detail goes here.</p>

The idea is that the whole thing can be closed (when only the summary is visible) or open (when both the summary and detail parts are visible). However, browser support is patchy and inconsistent, and styling options are limited.

Here’s how the element looks when open and closed in Firefox and Chrome:

Closed (Firefox) Open (Firefox) Closed (Chrome) Open (Chrome)
_images/ff-closed.png _images/ff-open.png _images/chrome-closed.png _images/chrome-open.png

Of course, docutils and Sphinx don’t offer any reStructuredText markup which maps to this HTML5 element. With the Sizzle theme, you can achieve a similar effect like this:

.. cssclass:: summary-detail

* :span:`The summary goes here.`

  The detail goes here.

The Sizzle theme code looks for this specific CSS class and arranges for it to be shown like this:

  • The summary goes here.

Custom Styles and JavaScript

If you have custom styles and/or JavaScript, you can install them in one of two ways, depending on the version of Sphinx you’re using. If you’re using Sphinx 1.8 or later, you should use configuration options in like this:

html_css_files = ['css/project.css']
html_js_files = ['js/project.js']

If you’re using an earlier Sphinx version than 1.8, then in your, have code something like this:

def setup(app):

The CSS file will be loaded after Sizzle’s own CSS, allowing you to tweak styles where needed. The JavaScript file will be added after all other external JavaScript files. Bear in mind that the Sizzle theme arranges to first add a JavaScript object to the DOM using a jQuery call:

$(document).data('sizzle', {on_load: []});  // code in the Sizzle theme

This is done before your custom JavaScript is included. If you want to have some JavaScript code of yours called after the entire document is loaded, you can do something like

function my_custom_function() {
  // whatever

var sizzle = $(document).data('sizzle');


in your custom JavaScript file. When the document has loaded, the Sizzle theme’s code calls any functions pushed onto the on_load array:

$(document).ready(function() {  // code in the Sizzle theme

  // other stuff omitted ...

  var sizzle = $(document).data('sizzle');

  if (sizzle.on_load) {
    sizzle.on_load.forEach(function(f) {

  // other stuff omitted ...


So your my_custom_function should get called once the document has loaded.

Example – styling columns in a table

Here’s an example function which I implemented for a project, using the functionality described above:

function add_column_styles() {
  $('table').each(function() {
    $(this).find('tr').each(function() {
      $(this).find('td, th').each(function(i) {
        $(this).addClass('col-' + i);

This adds a col-N class to every cell in the Nth column of every table, including header rows. By judicious application of CSS, you might be able to use this approach to style tables in your content as you wish. For instance,

/* centre all columns except the first */
#some-table td:not(.col-0), #some-table th:not(.col-0) {
  text-align: center;

/* apply padding to the first column only */
#some-table td.col-0, #some-table th.col-0 {
  padding-left: 6px;


The theme adapts well to smaller screens, as shown in the following images.

Appearance on a small screen Navigation menu on a small screen
_images/mobile_1.png _images/mobile_2.png

Glossary Improvements

Starting with version 0.0.9, there have been some improvements to Sphinx glossary functionality.


By default, you can see tooltips when you hover over a glossary term in documentation. You can try them out in the Supervisor documentation set: there are some glossary terms at the top of the home page - just hover over them to see the tooltips with the glossary definitions of those terms.

You can disable tooltips by setting enable_tooltips to False in the theme options.

New in version 0.0.9: The tooltip functionality was added and applied to glossary terms.

Code Block Improvements

Starting with version 0.0.9, code blocks with captions get a little button which, when clicked, copies the contents of the code block to the clipboard. The idea was shamelessly borrowed from recent Django documentation! Here’s an example:
def dump_node(node, level=0, file=sys.stdout):  # used for debugging only
    print('%s%r' %('  ' * level, node), file=file)
    for child in node.children:
        dump_node(child, level + 1, file=file)

New in version 0.0.9: The code block copy functionality was added.

Providing Customized Tooltips

Starting with version 0.0.9, you can provide customized tooltips. For example, here’s an info icon with a customized tooltip: If you hover over it, you’ll see a tooltip saying something like “This feature was added in version 0.0.9.” This was achieved using the following steps:

  • Have a span with a CSS class tc-infotip and another CSS class starting with tci-, where the suffix is treated as a key. to use when finding the tooltip’s HTML. In the above example, that’s done using the markup :fa:`info-circle,tc-infotip,tci-ver-0.0.9`. The tc-infotip class is used to style the content with the tip (by default, it just indicates via the cursor that help is available).

  • Immediately following that, have a span which has the tc-info class. IN the above example, that’s just `:span:`tc-info|` (the span here has no text; it simply serves as a marker for the preceding element. But it’s fine to have text, too, as in the examples below).

  • In, the custom_data theme option was set to have some pertinent information, like this:

      'custom_data': {
        'info-tips': {
            'ver-0.0.9': 'This feature was added in version 0.0.9.',
            'win-only': 'This doodad only works on Windows.',
            'linux-only': 'This thingummy is for Linux only.',

When the documentation is built, Python code in the Sizzle theme ensures that the contents of custom_data are made available to the JavaScript code in the built documentation. When the page is loaded, JavaScript code in the Sizzle theme looks for elements with class tc-info and for each of them, if an element is found immediately preceding it with a class beginning with tci-, that prefix is stripped off to provide a key (in this case, it would be ver-0.0.9. If that key is found in the info-tips mapping, the corresponding value is treated as HTML to appear in the tooltip. (If the key is not found, e.g. because missing or misspelt in custom_data['info-tips'], then no tooltip will appear.)

Of course, Sphinx has versionadded and versionchanged directives to provide this type of information in the body of the document. But this example is just for the purposes of illustration – in practice, this feature could be used to provide info-tips which are about platform-specific or product-specific features, with a suitable icon to draw attention to them. For example, to mark something as only working on Windows, or something else as only working on Linux.

New in version 0.0.9: Customized tooltip functionality was added.

Change Log

  • Changes for recent releases are shown here (click the arrow at left to expand).