Configuration#

If you want to use the insipid theme, only a single setting is required in your conf.py:

html_theme = 'insipid'

However, you may also want to change the default symbol for section title links from the default ¶ to something more meaningful like # or § or maybe 🔗:

html_permalinks_icon = '#'

If the sources of your documentation are hosted publicly, you should set:

html_copy_source = False

… and follow the instructions at html_show_sourcelink to get automatic source links in the page footer.

Theme Settings#

The insipid theme has many configuration parameters which can be specified with html_theme_options in your conf.py, for example like this:

Listing 1 A simple conf.py#
html_theme = 'insipid'
html_theme_options = {
    'body_centered': False,
    'breadcrumbs': True,
}

You can also have a look at the example below.

All available theme options are listed in the following sections.

insipid Settings#

The following settings are provided by the insipid theme. See below for default values.

body_centered#

Set to False if you want the body text to be left-aligned.

If body_max_width is None, this has no effect.

breadcrumbs#

Set to True to show breadcrumb navigation (including a “home” button) at the top of each page (via the page.html template).

initial_sidebar_visibility_threshold#

The visibility of the sidebar depends on the setting from the previous visit, which is stored in the browser’s localStorage. If no information is available (i.e., on the first visit), the sidebar is hidden, except if the browser window is wider than the given threshold (in pixels or any CSS unit). If None is given, or if JavaScript is disabled in the browser, the sidebar is initially hidden, regardless of screen width.

left_buttons#

List of templates to show on the left side of the title bar.

You can use one of the built-in templates (ending with -button.html):

search-button.html

A button to show/hide the search field.

Note

This is only shown if html_sidebars does not contain 'searchbox.html' or 'searchfield.html'.

fullscreen-button.html

A button to switch to fullscreen mode (and back again).

Note

This will only be shown if fullscreen mode is available.

repo-button.html

A Bitbucket/Gitlab/Github logo linking to the associated repository.

For this to work, you’ll have to provide some information in your conf.py via html_context:

html_context = {
    'display_gitlab': True,
    'gitlab_user': 'myuser',
    'gitlab_repo': 'myrepo',
}

Replace gitlab with bitbucket or github if the repository containing your source files is hosted on Bitbucket or Github, respectively.

If you use a different hosting platform, you can override this template entirely.

pdf-button.html

A link to the PDF version of your docs.

You’ll have to make sure that a PDF version is built and uploaded and you’ll have to provide the URL to that PDF file in your conf.py via html_context:

html_context = {
    'downloads': [
        ('pdf', 'https://example.org/my-docs.pdf'),
    ],
}

You can also create your own template file(s) located in your templates_path. It’s best to use <a> or <button type="button"> elements. You can include other templates, most notably icons.

For example, a “home” button could be made by creating a file named _templates/home-button.html (relative to your conf.py) with this content:

<a href="{{ pathto('index') }}" title="{{ docstitle|e }}">
  {% include 'icons/home.svg' %}
</a>

… and adding the file name to html_theme_options like this:

html_theme_options = {
    'left_buttons': [
        'home-button.html',
    ],
}
templates_path = ['_templates']

For help creating your own templates, see Templating.

right_buttons#

List of templates to show on the right side of the title bar.

See also

left_buttons

rightsidebar#

Set to True if you want to move the sidebar from the left to the right.

See also

nosidebar, html_sidebars

show_insipid#

Set to False to hide the “Insipid Theme” link in the footer.

sidebar_overlay_width#

When the browser window is narrower than this value (in pixels or any CSS unit) – e.g. on a small mobile device – the sidebar will (partially) cover the main text. Set to None to disable.

sidebar_transition#

Duration (and optional timing function) of the CSS transition effect for showing/hiding the sidebar.

strip_section_numbers#

Section numbers (if you use them at all) are by default removed from previous/next links and from the title bar. Set to False to show them.

topbar_transition#

Duration (and optional timing function) of the CSS transition effect for showing/hiding the title bar.

basic Settings#

The following settings are inherited from the basic theme (therefore, most Sphinx themes have them), but for some of the options, the default values have been changed.

body_max_width#

Maximal width of the main document text (in pixels or any CSS unit). Set it to None for unlimited width.

body_min_width#

Minimal width of the main document text (in pixels or any CSS unit).

globaltoc_collapse#

If True (the default), only the current section of the table of contents (TOC) in the sidebar is expanded. Set to False to expand everything.

globaltoc_includehidden#

If True, include sections from toctree directives with the :hidden: flag in the table of contents (TOC) in the sidebar. By default, hidden sections are not included.

navigation_with_keys#

If True, the left and right arrow keys can be used to turn pages.

Note

This is disabled by default in the basic theme (and therefore in most other themes as well), for reasons given in Sphinx PR #2064.

When using the insipid theme, however, this is enabled by default.

nosidebar#

Set to True to completely disable the sidebar.

See also

rightsidebar, html_sidebars

sidebarwidth#

Width of the sidebar (in pixels or any CSS unit).

Note

Whenever the sidebar is resized, its new width is stored in the browser’s “local storage”. Therefore, a changed sidebarwidth might not be immediately visible.

Default Values#

For default values, see:

Listing 2 insipid/theme.conf#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
[theme]
inherit = basic
stylesheet = insipid.css
sidebars = globaltoc.html, separator.html, indices.html
pygments_style = friendly

[options]
rightsidebar = false

left_buttons = search-button.html
right_buttons = fullscreen-button.html, repo-button.html

body_centered = true
breadcrumbs = false
strip_section_numbers = true

topbar_transition = 0.3s ease-out
sidebar_transition = 0.3s ease-out

show_insipid = true

sidebar_overlay_width = 39rem

initial_sidebar_visibility_threshold = 100rem

# Inherited from "basic" theme, but different default values:
body_min_width = unset
body_max_width = 45rem
navigation_with_keys = true
sidebarwidth = 19rem

Sphinx Settings#

Sphinx has a lot of settings – read the docs! Here we only show a small selection of configuration values which are relevant for the insipid theme.

html_copy_source#

When html_copy_source is True (which is the default), all source files are copied to the HTML output directory (into the _sources sub-directory). The string given by html_sourcelink_suffix is appended to each file name.

Note

This has to be set to False in order to show links to the source files on Bitbucket/Gitlab/Github, see html_show_sourcelink.

When html_show_sourcelink is True (which is the default), a link to the source file of each page is shown in the footer.

Traditionally, those links point to copies of the source files (when html_copy_source has its default value True).

However, when html_copy_source is False, the insipid theme (via the show-source.html template) will show links to the appropriate version of the source files on Bitbucket/Gitlab/Github, if the following fields of html_context are specified in your conf.py:

html_context = {
    'display_gitlab': True,
    'gitlab_user': 'myuser',
    'gitlab_repo': 'myrepo',
    'conf_py_path': '/path/to/doc/',
    'commit': '123abc',
}

The example above shows settings for Gitlab. Replace gitlab with bitbucket or github if the repository containing your source files is hosted on Bitbucket or Github, respectively. If the source files are hosted on a different service, you can manually override the template show-source.html.

The commit value should contain the hash (or tag name) of the commit which was used to create the docs. See this project’s conf.py for an example for how to obtain the relevant hash automatically via Git.

html_sidebars#

The content of the sidebar consists of the html_logo (if specified), followed by the list of templates in html_sidebars.

You can choose from templates provided by the basic theme, like globaltoc.html, localtoc.html, relations.html, searchbox.html, searchfield.html and sourcelink.html.

You can also select templates from the insipid theme: home.html, indices.html and separator.html.

Finally, you can create your own custom templates. It’s best to use <h3>, <h4> and <p class="caption"> elements for titles, as well as “normal” <p> and <ul> (containing <li> elements which themselves typically contain <a href="..."> links). To distinguish between internal and external links, you can use <a class="reference internal" ...> and <a class="reference external" ...>, respectively.

See also

Theme options rightsidebar and nosidebar

html_theme_options#

The value html_theme_options contains all custom theme settings.

language#

When a supported language is chosen, all UI strings will be translated accordingly.

Example#

You can look at the conf.py file of this very documentation:

Listing 3 conf.py of the insipid docs#
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
# Configuration file for Sphinx,
# see https://www.sphinx-doc.org/en/master/usage/configuration.html

import os

# -- Recommended settings -----------------------------------------------------

html_theme = 'insipid'

html_permalinks_icon = '#'

# If False, source links to Bitbucket/Github/GitLab are shown (using html_context)
html_copy_source = False

# Update this with your own repo information:
html_context = {
    'display_github': True,
    'github_user': 'mgeier',
    'github_repo': 'insipid-sphinx-theme',
    'conf_py_path': '/doc/',
    'READTHEDOCS': os.environ.get('READTHEDOCS', False),
    # The 'commit' field is overwritten below (with data from Git).
    # If you prefer, you can also get it from your build environment,
    # e.g. READTHEDOCS_GIT_COMMIT_HASH.
    'commit': '???',
}

# -- Settings for source code -------------------------------------------------

# Language used for syntax highlighting (default: 'python')
#highlight_language = 'none'

# Style of syntax highlighting
#pygments_style = 'monokai'

# -- Language settings --------------------------------------------------------

#language = 'es'

# Date format used in footer. Use empty string for (language-specific) default.
# 'sphinx_last_updated_by_git' extension provides modification dates per page.
#html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %Z'

# -- Theme configuration ------------------------------------------------------

html_theme_options = {
    #'body_centered': False,
    #'body_max_width': None,
    #'breadcrumbs': True,
    #'enable_search_shortcuts': False,
    #'globaltoc_collapse': False,
    #'globaltoc_includehidden': True,
    #'initial_sidebar_visibility_threshold': None,
    #'left_buttons': [
    #],
    #'navigation_with_keys': False,
    #'nosidebar': True,
    #'right_buttons': [
    #    'search-button.html',
    #],
    #'rightsidebar': True,
    #'show_insipid': False,
    #'sidebar_overlay_width': None,
    #'sidebar_transition': '1s ease-out',
    #'sidebarwidth': '10rem',
    #'strip_section_numbers': False,
    #'topbar_transition': '1.5s ease-out',
}

html_sidebars = {
   '**': [
       'github-badge.html',  # Custom template, see _templates/
       'home.html',
       'globaltoc.html',
       'separator.html',
       'indices.html',
   ],
   'showcase/different-sidebar': [
       'localtoc.html',
       'searchbox.html',
   ],
   'showcase/no-sidebar': [],
}

html_static_path = ['_static']
templates_path = ['_templates']

# -- Project information ------------------------------------------------------

project = 'insipid-sphinx-theme'
#html_title = 'Insipid Sphinx Theme'
html_short_title = 'insipid'
#copyright = '<insert year and copyright holder>'
#version = '3.14'
#release = '3.14.dev2'

html_logo = 'showcase/insipid.png'
html_favicon = '_static/favicon.svg'

# -- Page footer --------------------------------------------------------------

html_show_copyright = False
#html_show_sphinx = False
#html_show_sourcelink = False

# Only relevant when html_copy_source is True
#html_sourcelink_suffix = ''

# -- Miscellaneous settings ---------------------------------------------------

# Numbered figures, tables and code-blocks
numfig = True

html_secnumber_suffix = '\N{FIGURE SPACE}'

#html_compact_lists = False

#smartquotes = False

# Generate alphabetic index
#html_use_index = False

# Separate page per starting letter
#html_split_index = True

# Generate domain indices, e.g. Python module index
#html_domain_indices = False

# The default in Sphinx 4+ is 'inline'
#html_codeblock_linenos_style = 'table'

# -- Sphinx extensions --------------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinx.ext.viewcode',
    'sphinx_last_updated_by_git',
]

intersphinx_mapping = {
    'sphinx': ('https://www.sphinx-doc.org/', None),
}