If you don’t like this theme, no problem,
Sphinx has several Builtin themes to choose from and
you can find a large list of third-party Sphinx themes at
https://sphinx-themes.org/.
You can also search for Sphinx themes on PyPI, GitLab and Github.
The following list has been driving the development of this theme.
Those are the goals, but that doesn’t necessarily mean that any of them has
been reached (to a sufficient degree) yet.
The most important thing is your content.
It shouldn’t be outshined by some flashy theme.
The theme is supposed to stay in the background and out of the way.
This theme uses only very few (and only locally available) fonts,
very few (and quite dull) colors
and just a handful of simple symbols.
Most navigational tools can be hidden (and are in fact hidden by default),
providing a maximum of screen real estate for
and a minimum of distraction from your content.
Only if your browser window is extremely wide, the sidebar will be shown
on the initial visit. This can be configured with
initial_sidebar_visibility_threshold.
accessible
Help needed!
There are some aria-labels here and there,
but the accessibility could certainly be improved in many places.
mobile-friendly
This theme should work well on (reasonably modern) mobile devices.
Considerable care has been taken to make sure all the screen space is
available for content and not obstructed by ornamental junk.
configurable
The default settings should be perfectly fine for most people.
But doesn’t everyone sometimes like to be special?
Many features can be switched on and off (see Configuration),
and thanks to Sphinx’s great flexibility,
you can fine-tune and individualize virtually every aspect of the theme,
see Customization for details.
support for right-to-left languages
Help needed!
For now, there are no special arrangements in place
except for a measly rightsidebar theme option.
optional JavaScript
Some features (like resizing the sidebar, storing the sidebar state when
navigating between pages, hiding/showing the topbar, search,
fullscreen button) require JavaScript.
However, if JavaScript is disabled,
all content should still be perfectly readable and the navigation within
and between pages should still work well.
Even opening and closing the sidebar works without JavaScript.
support for all Sphinx features
The largest part of this documentation
(starting at Showcases)
is a showcase of (hopefully) all
things that can be generated with Sphinx (aside from arbitrary “raw” HTML).
If you find something that isn’t supported (or not shown in the docs),
please let us know!
back to the basics
This theme is derived from Sphinx’s basic theme
and only adds some hand-written HTML, CSS and JavaScript
(sprinkled with a pinch of Jinja2 markup).
Plus a few SVG icons from Font Awesome
(embedded in the HTML files – no external assets).
No external JavaScript framework is used,
and no extension-specific Python code is ever executed
(you can check the source code of insipid_sphinx_theme.setup()).
First of all, the insipid theme tries to not disable any features
that Sphinx (and its basic theme, see basic Settings) already has.
Here’s a little selection of features, some of them provided by Sphinx itself,
some added by the insipid theme:
auto-hiding topbar
The goal is to maximize (vertical) screen space and to get out of the way.
Therefore, the topbar disappears when scrolling down.
When scrolling up,
or when hovering over (or touching) the top part of the screen,
it re-appears.
The topbar contains some useful icons
(see left_buttons and right_buttons)
as well as the title of the current page.
When clicking on said title, the page is scrolled to the top
and the title of the parent document is displayed.
Clicking on that brings you to the parent document.
resizable sidebar
In addition to toggling its visibility,
the width of the sidebar can also be interactively changed by users.
The new width (and whether the sidebar is visible or not)
is stored in the browser’s “local storage”,
which means it will be remembered for the next visit.
The default width can be configured with the theme option
sidebarwidth,
the content of the sidebar can be configured with
html_sidebars (and html_logo).
On devices with a touchscreen,
the sidebar can be opened/closed with a swipe right/left gesture.
keyboard navigation
This is one of the features that’s provided by Sphinx,
but several third-party themes have inadvertently disabled it.
You can switch between pages using the left and right arrow keys.
This feature can be disabled with navigation_with_keys.
In addition to the left/right arrow keys,
several key combinations are provided using the accesskey HTML feature.
The way to use these keyboard shortcuts depends on the browser
and the operating system, typically involving holding the Alt key,
often combined with the Shift or the Control key.
For details, see e.g. MDN.
The following access keys are available in many Sphinx themes:
n for the next page;
p for the previous page;
u for up (to the parent page);
i for the index.
In addition to these, the insipid theme provides
s to show/hide the search field and
m for showing/hiding the sidebar (i.e. the menu).
fullscreen mode
When supported by the browser
(and when not overridden with right_buttons),
the topbar contains an icon for switching into (and out of)
fullscreen mode.
Navigating to another page will typically exit fullscreen mode.
translatable UI
All strings used in the user interface (including aria-labels)
are translatable and
they will be automatically replaced by their translations
when a supported language setting is used.
The RTD “badge” (for selecting versions, languages etc.)
is incorporated into the bottom of the insipid sidebar
(instead of floating around in the bottom right corner of the page).
Furthermore, a link to the connected Bitbucket/Github/GitLab repository
is automatically displayed in the topbar.
This can be disabled by overriding right_buttons.
Finally, if html_copy_source is set to False,
a “show source” link to the appropriate version of the page source
on Bitbucket/Github/GitLab is shown in the footer of each page.
The link can be disabled by setting
html_show_sourcelink to False.
Install the Python package insipid-sphinx-theme, e.g. with pip:
python3 -m pip install insipid-sphinx-theme
Depending on your Python installation,
you may have to use python instead of python3.
If you have installed the module already,
you can use the --upgrade flag to get the newest release.
Note
By default, a recent Sphinx version is required and automatically
installed when installing insipid-sphinx-theme.
Older Sphinx versions are supported to some degree
(some features might not be rendered as in newer versions, see
https://insipid-sphinx-theme.readthedocs.io/en/sphinx3/ and
https://insipid-sphinx-theme.readthedocs.io/en/sphinx4/),
but those older versions have to be installed manually
and insipid-sphinx-theme has to be installed
with the --no-deps flag.
Edit the conf.py file
(just create an empty file if it doesn’t exist yet,
or use sphinx-quickstart) and add/edit the line:
html_theme='insipid'
Make sure your source files are
in the same directory as your conf.py.
If you don’t have any source files yet,
you can start with a simple index.rst:
My Docs=======
Hello, world!
At some point, you’ll probably want to have more than one page.
You can use the toctree directive
to include additional pages.
Run Sphinx, e.g. by using:
python3 -m sphinx <source-dir> <build-dir>
… where <source-dir> is the directory
that contains your conf.py,
and <build-dir> is the place where the generated HTML files
should be written to.
For example, the full command could look something like this:
That should be it.
But there are many options (Configuration) and customization
possibilities (Customization) available.
Alternative Usage
It is convenient to install the theme as a Python package,
because this way Sphinx can find it easily
and you don’t have to worry about where the theme’s files are stored.
However, the package installation is not strictly necessary
(because the insipid theme is just a theme
and not a full-blown Sphinx extension).
If you don’t want to install the package,
you can instead use html_theme_path
to tell Sphinx where the directory containing the insipid directory is.
For example, you could include the insipid-sphinx-theme repository
as a Git submodule in your own repository and point to that submodule
in your conf.py:
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='#'
And if you happen to host your documentation on https://readthedocs.org/
and your sources on Bitbucket, Github or GitLab, you should set:
html_copy_source=False
This way, you will get automatic source links in the page footer.
See html_show_sourcelink for details.
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.
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:
You can also create your own template file(s) located in your
templates_path.
It’s best to use <a> or <buttontype="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:
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.
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.
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.
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.
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.
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:
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.
The commit value should contain the hash (or tag name)
of the commit which was used to create the docs.
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.
Finally, you can create your own custom templates.
It’s best to use <h3>, <h4> and <pclass="caption"> elements
for titles, as well as “normal” <p> and <ul>
(containing <li> elements which themselves typically
contain <ahref="..."> links).
To distinguish between internal and external links, you can use
<aclass="referenceinternal"...> and
<aclass="referenceexternal"...>, respectively.
Adding your own CSS files is very easy.
Just add their file names to html_css_files
and make sure they are living in a directory
that’s part of html_static_path.
For example, if the path to your CSS file is _static/funky.css
(relative to your conf.py), you can use something like this:
Each HTML page generated by Sphinx is pieced together from multiple components,
called templates.
You can create your own templates in order to customize certain parts.
All your templates must live in a directory that’s part of the
templates_path (or a sub-directory thereof).
templates_path=['_templates']
Some parts of the generated pages are just lists of templates,
namely html_sidebars,
left_buttons and
right_buttons.
You can create arbitrary new files and add them to those lists.
You can also extend (or completely replace) existing templates
(layout.html, page.html,
footer.html etc.).
For example, you can extend the template layout.html
by creating your own file named layout.html:
{%extends"!layout.html"%}{%blockhtmltitle%}<title>Best docs ever!</title>{%endblock%}{%blockrelbar1%}{%endblock%}{%blockrelbar2%}{%endblock%}{%blockcomments%}<!-- embed some comment service here -->{%endblock%}{%blockfooter%}{{super()}}<!-- embed some analytics service here -->{%endblock%}
The relbar1 and relbar2 blocks are used to overwrite
the previous/next links at the top and bottom of each page, respectively.
Use {{super()}} to include the contents of the original block.
Otherwise, the contents are overwritten.
If you don’t use the extends tag,
you can completely replace a given template.
By leaving the file empty, you can disable a template.
For example, if the setting copyright is not flexible enough
(because it inserts a “copyright” symbol which may not be desired),
one could create a customized note by replacing the existing template
copyright.html:
The icons used by the insipid theme are templates as well.
Their content is copied into the generated HTML files.
You can replace icons the same way as any other template.
For example, to replace the icons/menu.svg icon,
simply store a new SVG file at _templates/icons/menu.svg.
To include the contents of an SVG file in your own HTML template,
use the include tag, e.g.:
If you want to re-use your custom templates in multiple Sphinx projects,
you can create your own theme derived from the insipid theme
(you can of course also derive from any other theme, if you prefer!).
For all the details, have a look at HTML Theming.
Here, we’ll just give a quick summary.
You should create a directory named after your theme,
containing all your custom templates.
Note
You’ll have to change your templates from using
{%extends"!layout.html"%}
to using
{%extends"insipid/layout.html"%}
In the same directory,
you’ll also have to create a file named theme.conf
with a content similar to this:
[theme]inherit=insipidstylesheet=???.csssidebars=???.html, ???.html, ???.htmlpygments_style=???[options]left_buttons=???.html, ???.htmlright_buttons=???.htmlbreadcrumbs=trueyour_own_option1=4emyour_own_option2=true# and so on and so on ...
Everything except inherit is optional
(and even that can be set to none
if you insist on not deriving from any theme).
You should also create a sub-directory named static
containing your main CSS file (and probably additional CSS files)
and any custom JavaScript files you want to use.
Write the name of your main CSS file to the stylesheet field in your
theme.conf.
Remove the stylesheet field if you don’t want to use your own CSS file.
By default, the CSS file insipid.css will not be included,
but basic.css and insipid-sidebar-readthedocs.css
will be included.
To include insipid.css, add this to your layout.html template:
Similarly, you can add further custom CSS files, if you want.
Note
You could alternatively use this in your CSS file:
@import'insipid.css';
But this will increase the load time of the HTML pages!
If you want to use custom JavaScript files,
store them in the static sub-directory of your theme directory
(they will automatically be copied into the _static sub-directory
of the HTML output directory)
and add something like this to your layout.html template:
If you find bugs, errors, omissions or other things that need improvement,
please create an issue or a pull request at
https://github.com/mgeier/insipid-sphinx-theme/.
Contributions are always welcome!
When installing this way, you can quickly try other Git
branches (in this example the branch is called “another-branch”):
gitcheckoutanother-branch
If you want to go back to the “master” branch, use:
gitcheckoutmaster
To get the latest changes from Github, use:
gitpull--ff-only
If you used the --recursive option when cloning,
the Font-Awesome submodule (containing the SVG icons)
will be checked out automatically.
If not, you can get the submodule with:
Whenever a Pull Request (PR) is created on
https://github.com/mgeier/insipid-sphinx-theme/pull/,
the documentation is automatically built on https://readthedocs.org/.
On the PR page, find the latest commit and click on its green check mark
(or on the red “x” in case of a test failure),
look for the readthedocs.org entry and click on “Details”
to see the auto-generated HTML pages.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
Curabitur pretium tincidunt lacus. Nulla gravida orci a odio. Nullam varius,
turpis et commodo pharetra, est eros bibendum elit, nec luctus magna felis
sollicitudin mauris. Integer in mauris eu nibh euismod gravida. Duis ac tellus
et risus vulputate vehicula. Donec lobortis risus a elit. Etiam tempor. Ut
ullamcorper, ligula eu tempor congue, eros est euismod turpis, id tincidunt
sapien risus a quam. Maecenas fermentum consequat mi. Donec fermentum.
Pellentesque malesuada nulla a mi. Duis sapien sem, aliquet nec, commodo eget,
consequat quis, neque. Aliquam faucibus, elit ut dictum aliquet, felis nisl
adipiscing sapien, sed malesuada diam lacus eget erat. Cras mollis scelerisque
nunc. Nullam arcu. Aliquam consequat. Curabitur augue lorem, dapibus quis,
laoreet et, pretium ac, nisi. Aenean magna nisl, mollis quis, molestie eu,
feugiat in, orci. In hac habitasse platea dictumst.
Multiple spaces are not collapsed in inline literals: abc.
very/long/literals/are/broken/without/inserting/a/hyphen.
averyveryveryverylongsinglewordisalsoforciblybrokenatsomepointwithoutinsertingahyphen.
Text after left-aligned image.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Text after right-aligned image.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Text after “normal” figure.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Some more text. Some more text.
Text after right-aligned figure.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
Some more text.
A long long long long long long long long long long long long
long long long long long long long long long long long long long long long
admonition title
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
x
A long long long long long long long long long long long long
long long long long long long long long long long long long long long long
topic title
A single list item containing multiple paragraphs:
A paragraph.
Another paragraph.
Multiple list items containing a single paragraph each:
A paragraph.
Another paragraph.
Multiple list items, some containing multiple paragraphs:
A paragraph.
Another paragraph.
A third paragraph.
Nested lists, each item containing a single paragraph
and/or a single nested list, each item containing …
A paragraph.
Another paragraph.
A second level paragraph.
A second level paragraph with significantly more text in it.
So much text that there will be at least one line break within the paragraph.
This will show the difference in spacing between lines and list items.
Do you see a difference?
Or is it the same?
Another first level paragraph.
An example that doesn’t fulfill this rule (only the nested sub-list does):
A paragraph.
Another paragraph.
A second level paragraph
A second level paragraph
Yet another paragraph.
Compact lists can be manually forced by using the compact class:
A paragraph.
Another paragraph.
A third paragraph.
Non-compact lists can be manually forced by using the open class:
A paragraph.
Another paragraph.
Definition term
bullet point in definition
Normal paragraph in definition.
Admonition
bullet point in admonition
Topic
bullet point in topic
Compact list in topic
A paragraph.
Another paragraph.
Non-compact list in topic
A paragraph.
Another paragraph.
A third paragraph.
A list item containing admonitions containing further lists:
A structure where information about all documents under the root is
saved, and used for cross-referencing. The environment is pickled
after the parsing stage, so that successive runs only need to read
and parse new and changed documents.
Since the field marker may be quite long, the second
and subsequent lines of the field body do not have to line up
with the first line, but they must be indented relative to the
field name marker, and they must line up with each other.
A block quote may end with an attribution:
a text block beginning with --, ---, or a true em-dash,
flush left within the block quote.
If the attribution consists of multiple lines,
the left edges of the second and subsequent lines must align.
—docutils documentation
Multiple block quotes may occur consecutively
if terminated with attributions:
A pull-quote is a small selection of text “pulled out and quoted”,
typically in a larger typeface.
Pull-quotes are used to attract attention, especially in long articles.
With docutils versions older than 0.18, the HTML line breaks in the left
column are not working correctly. Make sure to use at least
docutils>=0.18, which is supported since Sphinx version 5.0.
To check whether HTML escaping works, both the file name and the title contain
strange characters.
The double quotes character in the title is only problematic when
smartquotes is set to False.
57html_sidebars={58'**':[59'github-badge.html',# Custom template, see _templates/60'home.html',61'globaltoc.html',62'separator.html',63'indices.html',64],65'showcase/different-sidebar':[66'localtoc.html',67'searchbox.html',68],69'showcase/no-sidebar':[],70}
If you don’t like the search button in the topbar,
you can also put a search field into the sidebar
by selecting the template searchbox.html or searchfield.html.
Like the search button, this is only available when JavaScript is enabled.
57html_sidebars={58'**':[59'github-badge.html',# Custom template, see _templates/60'home.html',61'globaltoc.html',62'separator.html',63'indices.html',64],65'showcase/different-sidebar':[66'localtoc.html',67'searchbox.html',68],69'showcase/no-sidebar':[],70}
If you don’t want to show the sidebar at all,
you can disable it globally with the theme option nosidebar.
Use the next and previous links at the top and the bottom of each page
to flip through the pages.
Alternatively, you can use the right and left arrow keys
on your keyboard.
Some additional keyboard shortcuts
are provided via the accesskey feature:
n next,
p previous,
u up (= to the parent page),
i index,
s search and
m menu (= open/close sidebar).
Click on the hamburger button in the topbar
to open and close the sidebar.
The width of the sidebar can be adjusted by dragging its border.
Click on the title in the topbar to scroll to the top of the page,
if already at the top, go “up” to the parent page
(eventually ending up on this very page).
On touch-enabled devices:
Tap at the top of the page to show the topbar (if it was scrolled away);
swipe from the left edge to show the sidebar,
swipe towards the left to hide it.
