Configuration§
If you want to use the insipid
theme,
only a single setting is required in your conf.py
:
html_theme = 'insipid'
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:
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
isNone
, this has no effect.
- breadcrumbs§
Set to
True
to show breadcrumb navigation (including a “home” button) at the top of each page (via thepage.html
template).
- 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'
.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.
Note
If your docs are hosted on https://readthedocs.org/ this should work automagically. If not, you’ll have to provide some information via
html_context
:html_context = { 'display_gitlab': True, 'gitlab_user': 'myuser', 'gitlab_repo': 'myrepo', }
Replace
gitlab
withbitbucket
orgithub
if the repository containing your source files is hosted on Bitbucket or Github, respectively.pdf-button.html
A link to the PDF version of your docs.
Note
If your docs are hosted on https://readthedocs.org/ (and if you’ve enabled PDF builds) this should work automagically. If not, you’ll have to provide the URL to the PDF file 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 caninclude
other templates, most notably icons.For example, a “home” button could be made by creating a file named
_templates/home-button.html
(relative to yourconf.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
- rightsidebar§
Set to
True
if you want to move the sidebar from the left to the right.See also
- 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 toFalse
to expand everything.
If
True
, include sections fromtoctree
directives with the:hidden:
flag in the table of contents (TOC) in the sidebar. By default, hidden sections are not included.
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
- 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:
1[theme]
2inherit = basic
3stylesheet = insipid.css
4sidebars = globaltoc.html, separator.html, indices.html
5pygments_style = friendly
6
7[options]
8rightsidebar = false
9
10left_buttons = search-button.html
11right_buttons = fullscreen-button.html, repo-button.html
12
13body_centered = true
14breadcrumbs = false
15strip_section_numbers = true
16
17topbar_transition = 0.3s ease-out
18sidebar_transition = 0.3s ease-out
19
20show_insipid = true
21
22sidebar_overlay_width = 39rem
23
24# Inherited from "basic" theme, but different default values:
25body_min_width = unset
26body_max_width = 45rem
27navigation_with_keys = true
28sidebarwidth = 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
isTrue
(which is the default), all source files are copied to the HTML output directory (into the_sources
sub-directory). The string given byhtml_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, seehtml_show_sourcelink
.
- html_show_sourcelink§
When
html_show_sourcelink
isTrue
(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 valueTrue
).However, when
html_copy_source
isFalse
, theinsipid
theme (via theshow-source.html
template) will show links to the appropriate version of the source files on Bitbucket/Gitlab/Github.Note
This should work automagically if your docs are hosted on https://readthedocs.org/. If not, you have to manually provide the necessary information via
html_context
: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
withbitbucket
orgithub
if the repository containing your source files is hosted on Bitbucket or Github, respectively.The
commit
value should contain the hash (or tag name) of the commit which was used to create the docs.
- html_sidebars§
The content of the sidebar consists of the
html_logo
(if specified), followed by the list of templates inhtml_sidebars
.You can choose from templates provided by the
basic
theme, likeglobaltoc.html
,localtoc.html
,relations.html
,searchbox.html
andsourcelink.html
.You can also select templates from the
insipid
theme:home.html
,indices.html
andseparator.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
andnosidebar
- html_theme_options§
The value
html_theme_options
contains all custom theme settings.
Example§
You can look at the conf.py
file of this very documentation:
1# Configuration file for Sphinx,
2# see https://www.sphinx-doc.org/en/master/usage/configuration.html
3
4# -- Recommended settings -----------------------------------------------------
5
6html_theme = 'insipid'
7
8html_permalinks_icon = '\N{SECTION SIGN}'
9
10# -- Recommended settings for readthedocs.org ---------------------------------
11
12# If False, source links to Bitbucket/Github/GitLab are shown
13html_copy_source = False
14
15# -- Settings for source code -------------------------------------------------
16
17# Language used for syntax highlighting (default: 'python')
18#highlight_language = 'none'
19
20# Style of syntax highlighting
21#pygments_style = 'monokai'
22
23# -- Language settings --------------------------------------------------------
24
25#language = 'es'
26
27# Date format used in footer. Use empty string for (language-specific) default.
28# 'sphinx_last_updated_by_git' extension provides modification dates per page.
29#html_last_updated_fmt = '%Y-%m-%d %H:%M:%S %Z'
30
31# -- Theme configuration ------------------------------------------------------
32
33html_theme_options = {
34 #'body_centered': False,
35 #'body_max_width': None,
36 #'breadcrumbs': True,
37 #'globaltoc_collapse': False,
38 #'globaltoc_includehidden': True,
39 #'left_buttons': [
40 #],
41 #'navigation_with_keys': False,
42 #'nosidebar': True,
43 #'right_buttons': [
44 # 'search-button.html',
45 #],
46 #'rightsidebar': True,
47 #'show_insipid': False,
48 #'sidebar_overlay_width': None,
49 #'sidebar_transition': '1s ease-out',
50 #'sidebarwidth': '10rem',
51 #'strip_section_numbers': False,
52 #'topbar_transition': '1.5s ease-out',
53}
54
55html_sidebars = {
56 '**': [
57 'github-badge.html', # Custom template, see _templates/
58 'home.html',
59 'globaltoc.html',
60 'separator.html',
61 'indices.html',
62 ],
63 'showcase/no-sidebar': [], # To demonstrate a page without a sidebar
64}
65
66html_static_path = ['_static']
67templates_path = ['_templates']
68
69# -- Project information ------------------------------------------------------
70
71project = 'insipid-sphinx-theme'
72#html_title = 'Insipid Sphinx Theme'
73html_short_title = 'insipid'
74#copyright = '<insert year and copyright holder>'
75#version = '3.14'
76#release = '3.14.dev2'
77
78html_logo = 'showcase/insipid.png'
79html_favicon = '_static/favicon.svg'
80
81# -- Page footer --------------------------------------------------------------
82
83html_show_copyright = False
84#html_show_sphinx = False
85#html_show_sourcelink = False
86
87# Only relevant when html_copy_source is True
88#html_sourcelink_suffix = ''
89
90# -- Miscellaneous settings ---------------------------------------------------
91
92# Numbered figures, tables and code-blocks
93numfig = True
94
95html_secnumber_suffix = '\N{FIGURE SPACE}'
96
97#html_compact_lists = False
98
99#smartquotes = False
100
101# Generate alphabetic index
102#html_use_index = False
103
104# Separate page per starting letter
105#html_split_index = True
106
107# Generate domain indices, e.g. Python module index
108#html_domain_indices = False
109
110# The default in Sphinx 4+ is 'inline'
111#html_codeblock_linenos_style = 'table'
112
113# -- Sphinx extensions --------------------------------------------------------
114
115extensions = [
116 'sphinx.ext.autodoc',
117 'sphinx.ext.autosummary',
118 'sphinx.ext.intersphinx',
119 'sphinx.ext.viewcode',
120 'sphinx_last_updated_by_git',
121]
122
123intersphinx_mapping = {
124 'sphinx': ('https://www.sphinx-doc.org/', None),
125}
126