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 tofalse
.globaltoc_depth
– as for Guzzle: the depth to which the global TOC is expanded. Defaults to5
.globaltoc_includehidden
– as for Guzzle: whether to include hidden entries in the global TOC. Defaults totrue
.project_logo_name
– this replaces Guzzle’sproject_nav_name
. The name change reflects that the value can be shown elsewhere than in a navigation panel.sitemap_url
– this replaces Guzzle’sbase_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 toNone
.google_analytics_id
– this replaces Guzzle’sgoogle_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 totrue
- set it toFalse
to hide the link.show_filter
– controls whether a filter to apply to TOC titles is shown. This defaults totrue
- set it toFalse
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 totrue
- set it toFalse
to disable tooltips.glossary_permalinks
– controls if glossary terms have permalinks. This defaults totrue
- set it toFalse
to disable the permalinks.
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.
Sidebar¶
The sidebar contains the following, from top to bottom:
- If the browser window isn’t wide enough to accommodate it, the search box.
- The heading “Table of Contents”, alongside which there is a left chevron ( ) which can be clicked on to collapse the sidebar.
- A “Filter by title” input box. If there is a long list of TOC entries, this
is handy to be able to filter the TOC entries by title. If you type into it,
only TOC entries with titles matching the filter text will be shown. The
show_filter
theme option can be used to control the visibility of the box.
If the sidebar is collapsed, you can bring it back by hovering the mouse at the left edge of the browser window for a second or two.
You can also hide and show the sidebar via the keyboard:
- Press Control-left arrow to hide it.
- Press Control-right arrow to show it.
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) |
---|---|---|---|
![]() |
![]() |
![]() |
![]() |
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 |
---|---|
![]() |
![]() |
Glossary Improvements¶
Starting with version 0.0.9, there have been some improvements to Sphinx glossary functionality.
Tooltips¶
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.
Permalinks¶
In the glossary, the term headings have a hover-over permalink which allows you to bookmark them by right-clicking – the same as headings.
You can disable glossary permalinks by setting glossary_permalinks
to
False
in the theme options.
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)