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).

Layout

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.

Typography

  • Font Awesome is integrated. You can use the markup role fa to introduce an icon into your content. For example, the markup :fa:`diamond` produces in the finished output.

  • 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) }
    

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 section on Summary-Detail Lists gives an example 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:

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

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 conf.py 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 conf.py, have code something like this:

def setup(app):
    app.add_stylesheet('css/project.css')
    app.add_javascript('js/project.js')

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');

sizzle.on_load.push(my_custom_function);

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) {
      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;
}

Device-Friendliness

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