An Insipid Sphinx Theme§
- Quick Start
Install the Python package
insipid-sphinx-theme
Add
html_theme = 'insipid'
to yourconf.py
Run Sphinx!
- Online documentation (and example of use)
- Source code repository (and issue tracker)
- License
BSD-2-Clause (same as Sphinx itself), for more information take a look at the
LICENSE
file.SVG icons from Font Awesome, CC BY 4.0.
Introduction§
This Sphinx theme was very much inspired by (i.o.w. ripped off of) mdBook.
Some further ideas were stolen from the Sphinx themes sphinx_typlog_theme (https://readthedocs.org/ badge), sphinx_material (previous/next arrows in relbar), sphinx_book_theme (fullscreen button), as well as websites like Github, MDN, and many others.
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.
Goals§
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.
If you have suggestions how to come closer to these goals, please create an issue or – even better! – a pull request at https://github.com/mgeier/insipid-sphinx-theme/.
- boring
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.
- accessible
Help needed! There are some
aria-label
s 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 hiding/resizing navigational tools, 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 reasonably well.
- 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
basic
s 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 (except for jQuery and underscore.js, which are already part of thebasic
theme), and no extension-specific Python code is ever executed (you can check the source code ofinsipid_sphinx_theme.setup()
).
Features§
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
andright_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 withhtml_sidebars
(andhtml_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-label
s) are translatable and they will be automatically replaced by their translations when a supportedlanguage
setting is used.- support for https://readthedocs.org/
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 toFalse
, 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 settinghtml_show_sourcelink
to False.
Installation and Usage§
Make sure you have Python installed.
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 ofpython3
. If you have installed the module already, you can use the--upgrade
flag to get the newest release.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 simpleindex.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 yourconf.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:python3 -m sphinx doc html-files
For more options, see sphinx-build.
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
:
html_theme_path = ['path-to-submodule/src/insipid_sphinx_theme']
html_theme = 'insipid'
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.
Set to
True
to show breadcrumb navigation (including a “home” button) at the top of each page (via thepage.html
template).
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.
List of templates to show on the right side of the title bar.
See also
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.
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.
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.
Set to
True
to completely disable the sidebar.See also
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 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 | [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
# 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
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.
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 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 | # Configuration file for Sphinx,
# see https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Recommended settings -----------------------------------------------------
html_theme = 'insipid'
# Set to empty string to disable links to sections
html_add_permalinks = '\N{SECTION SIGN}'
# -- Recommended settings for readthedocs.org ---------------------------------
# If False, source links to Bitbucket/Github/GitLab are shown
html_copy_source = False
# -- 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,
#'globaltoc_collapse': False,
#'globaltoc_includehidden': True,
#'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/
'globaltoc.html',
'separator.html',
'indices.html',
],
'showcase/no-sidebar': [], # To demonstrate a page without a 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
# This will be the default in Sphinx 4+
#html_codeblock_linenos_style = 'inline'
# -- 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),
}
|
Customization§
If you want to go beyond Configuration, you’ve come to the right page!
Custom CSS files§
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:
html_css_files = ['funky.css']
html_static_path = ['_static']
Custom JavaScript Files§
Similarly, you can add JavaScript files located in the
html_static_path
by adding their paths to html_js_files
.
The JavaScript frameworks jQuery and underscore.js are available
(using $
and $u
, respectively).
Custom Templates§
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" %}
{% block htmltitle %}
<title>Best docs ever!</title>
{% endblock %}
{% block relbar1 %}{% endblock %}
{% block relbar2 %}{% endblock %}
{% block comments %}
<!-- embed some comment service here -->
{% endblock %}
{% block footer %}
{{ 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
:
Dedicated to the public domain with
<a href="https://creativecommons.org/publicdomain/zero/1.0/"
class="reference external">CC0 1.0</a>.
For further information, see Templating.
Custom SVG Icons§
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.:
<a href="https://mastodon.online/@...">
{% include 'icons/mastodon.svg' %}
</a>
Derive Your Own Theme§
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 = insipid
stylesheet = ???.css
sidebars = ???.html, ???.html, ???.html
pygments_style = ???
[options]
left_buttons = ???.html, ???.html
right_buttons = ???.html
breadcrumbs = true
your_own_option1 = 4em
your_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:
{% extends "insipid/layout.html" %}
{% block css %}
<link rel="stylesheet" href="{{ pathto('_static/insipid.css', 1) }}" type="text/css" />
{{ super() }}
{% endblock %}
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:
{% block scripts %}
{{ super() }}
<script defer src="{{ pathto('_static/my-script.js', 1) }}"></script>
{% endblock %}
If you want your JavaScript code to be available during page load,
drop the defer
flag.
For more information and inspiration,
have a look at the insipid
theme’s sources
and at the aforementioned HTML Theming page.
Contributing§
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!
Development Installation§
Instead of pip-installing the latest release from PyPI, you should get the newest development version (a.k.a. “master”) from Github:
git clone https://github.com/mgeier/insipid-sphinx-theme.git --recursive
cd insipid-sphinx-theme
python3 -m pip install -e .
… where -e
stands for --editable
.
When installing this way, you can quickly try other Git branches (in this example the branch is called “another-branch”):
git checkout another-branch
If you want to go back to the “master” branch, use:
git checkout master
To get the latest changes from Github, use:
git pull --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:
git submodule update --init
Building the Documentation§
If you make changes to the documentation, you should create the HTML pages locally using Sphinx and check if they look OK.
Initially, you might need to install a few packages that are needed to build the documentation:
python3 -m pip install -r doc/requirements.txt
To (re-)build the HTML files, use:
python3 setup.py build_sphinx
The generated files will be available in the directory build/sphinx/html/
.
Version History§
- Version 0.2.1 – 2020-10-23 – PyPI – diff
Fix line numbers for Pygments 2.7
Use higher values for z-index
- Version 0.2.0 – 2020-10-18 – PyPI – diff
Color scheme update: background colors are now lighter, duller and most importantly more insipid
- Version 0.1.0 – 2020-08-05 – PyPI
Initial release
Showcases§
This Documentation§
The documentation pages you are reading right now
are meant to be a showcase for how
certain Sphinx features look with the insipid
theme.
The following pages try to show all HTML constucts that can be created with Sphinx.
If you notice that something is missing, please create a bug report at https://github.com/mgeier/insipid-sphinx-theme/issues/!
Further Showcases§
The docutils
documentation has a demo document (source file) and
there are showcases
– rendered for many themes –
at https://sphinx-themes.org/.
Furthermore, several Sphinx themes have showcases in their documentation:
Basic Formatting§
Paragraphs§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#paragraphs
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.
After the line.
Compound Paragraphs§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph
The code
print('Hello, world!')
will show a message.
Compound paragraph in admonition
The code
print('Hello, world!')
will show a message.
Compound paragraph in topic
The code
print('Hello, world!')
will show a message.
Line Blocks§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
Inline Markup§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#inline-markup
Normal Inline Literal
Emphasis Strong Emphasis.
Hyperlinks§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks
Other page: Code Blocks.
Some file: insipid.png
.
Math equation: (9.1).
Footnotes§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#footnotes
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes
Footnote 1 and *. And some more: 2, 2, 2, 2.
- 1
This is an auto-numbered footnote. There is a lot of additional text, so there will be a line break and we will see how the second line is indented.
- 2(1,2,3,4)
Auto-numbered, multiple mentions.
- *
This is an auto-symbol footnote.
Admonition title with footnote 3
Footnote † in admonition
text.
Citations§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#citations
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#citations
Here is a citation reference: The Title [CIT2002]. And another citation reference: [CIT2020]. Another mention of the same citation: [CIT2020].
Other Semantic Markup§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#other-semantic-markup
abbr: LIFO –
command: rm –
dfn: term –
file: name.ext
–
guilabel: Cancel –
kbd: Control + x Control + f –
mailheader: Content-Type –
makevar: AM_CFLAGS –
manpage: ls(1), man –
menuselection: –
mimetype: text/plain –
newsgroup: comp.lang.python –
program: rm –
regexp: a*
–
samp: print(1+variable)
(as compared to print(1)
) –
pep: PEP 8 –
rfc: RFC 2822
Images§
Image§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#image
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images
Text after “normal” image.
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.
Image in admonition
Image in topic
Quoted image:
Note
Note after left-aligned image.
Topic title
Topic after left-aligned image.
Left-aligned image before a new section:
Scaled Image§
Figure§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
A link (needs numfig): Fig. 3.1.
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 left-aligned figure.
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.
Figure in admonition
Figure in topic
Quoted figure:
Scaled Figure§
Code
Blocks§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#showing-code-examples
Literal Blocks§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks
This is a code sample:
print('Hello, world!')
Quoted Literal Blocks§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#quoted-literal-blocks
Supported initial characters:
! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
:
! every line
! must
! start with the same character
code-block
Directive§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
print('Hello,')
print('wooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooorld!')
# another code block
No language:
┌─┬┐ ╔═╦╗ ╓─╥╖ ╒═╤╕
│ ││ ║ ║║ ║ ║║ │ ││
├─┼┤ ╠═╬╣ ╟─╫╢ ╞═╪╡
└─┴┘ ╚═╩╝ ╙─╨╜ ╘═╧╛
┌───────────────────┐
│ ╔═══╗ Some Text │▒
│ ╚═╦═╝ in the box │▒
╞═╤══╩══╤═══════════╡▒
│ ├──┬──┤ │▒
│ └──┴──┘ │▒
└───────────────────┘▒
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
:linenos:
option:
1 2 | print('Hello,')
print('wooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooorld!')
|
1 | # another code block
|
:linenos:
with :lineno-start:
:
12345 12346 | print('Hello,')
print('world!')
|
:emphasize-lines:
def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')
:emphasize-lines:
and :linenos:
:
1 2 3 4 5 | def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')
|
:caption:
:
print('Hello, world!')
:caption:
and :linenos:
:
1 2 | print('Hello,')
print('world!')
|
See also [source] link in insipid_sphinx_theme
.
parsed-literal
Directive§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal
Code block with inline markup, e.g. literal text
*.
- *
Having
literal text
within more literal text probably doesn’t make a lot of sense.
Code block with nothing special
Warning
Syntax highlighting (including providing a background color) is sometimes broken, see https://github.com/sphinx-doc/sphinx/issues/2167.
Doctest Blocks§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks
>>> print('this is a Doctest block')
this is a Doctest block
Nesting§
Note
'code in note'
Some text with inline code
.
'some more code'
Warning
1 2 3 4 5 | def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')
|
Topic
1 2 3 4 5 | def some_function():
interesting = False
print('This line is highlighted.')
print('This one is not...')
print('...but this one is.')
|
'code in quote'
Code After Sidebar
==================
.
.
.
.
.
.
.
A long long long long long long long long long long long long long line.
Admonitions§
Specific Admonitions§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions
In many themes only note
and warning
are supported!
Attention
Attention text and inline code
.
Caution
Caution text and inline code
.
Danger
Danger text and inline code
.
Error
Error text and inline code
.
Hint
Hint text and inline code
.
Important
Important text and inline code
.
Note
Note text and inline code
.
Tip
Tip text and inline code
.
Warning
Warning text and inline code
.
Generic Admonitions§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#generic-admonition
Topic§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic
Topic title with a link and code
Topic text and inline code
.
Sidebar§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar
Text after first sidebar
directive.
Text after second sidebar
directive.
Block quote after sidebar.
—Anonymous
Note
Note after sidebar
.
Topic after sidebar
.
Text.
Warning
Warning after sidebar
.
See also
seealso
after sidebar
Admonition-like Constructs§
https://www.sphinx-doc.org/en/master/extdev/nodes.html#new-admonition-like-constructs
See also
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-seealso
and some inline code
See also
Text.
- Module
insipid_sphinx_theme
Documentation of the
insipid_sphinx_theme
module.- Sphinx Documentation
Documentation for Sphinx.
New in version 3.14: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded
Changed in version 3.14: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionchanged
Deprecated since version 3.14: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-deprecated
Nesting§
Note
Warning
This is a warning.
Note
Inner note text.
This is the warning again.
Topic
Note
Topic within admonition is not allowed! Topic within topic neither!
Topic
Warning
Deep nesting ahead:
See also
- Note
Note
You shouldn’t use such deep nesting.
- Warning
Warning
Really!
Topic
See also
Text.
See also
Note
Note text.
Note
Admonition in a block quote.
Overflow§
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
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 |
Lists§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks
Note
The configuration value html_compact_lists
influences the display of lists!
Bullet Lists§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists
A single list item containing a single paragraph:
A paragraph.
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.
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:
Compact list in admonition
A paragraph.
Another paragraph.
Non-compact list in admonition
A paragraph.
Another paragraph.
A third paragraph.
Enumerated Lists§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists
Item 1 initial text.
Item 1a.
Item 1b.
Item 2a.
Item 2b.
Arabic numerals.
lower alpha)
(lower roman)
upper alpha.
upper roman)
Lists that don’t start at 1:
Three
Four
C
D
iii
iv
More than four
Nested lists, each item containing a single paragraph and/or a single nested list, each item containing …
Paragraph.
Paragraph.
Second level paragraph
Third level paragraph
Another third level paragraph
Another second level paragraph
Successive lists:
Paragraph.
A paragraph in a new list.
Admonition
enumerated list item in admonition
Topic
enumerated list item in topic
hlist
§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-hlist
|
|
|
Admonition
|
|
|
Topic
|
|
|
Definition Lists§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists
- term 1
Definition 1.
- term 2
Definition 2, paragraph 1.
Definition 2, paragraph 2.
- term 3classifier
Definition 3.
- term 4classifier oneclassifier two
Definition 4.
- term with
code
and bold Definition with
code
and bold.
Admonition
- term with
code
and bold in admonition
Topic
- term with
code
and bold in topic
Glossary§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary
Example link: source directory (term will be highlighted).
- environment
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.
- source directory
The directory which, including its subdirectories, contains all source files for one Sphinx project.
- term 1
- term 2
Definition of both terms.
- term with
code
and bold Definition with
code
and bold.
Admonition
- term in admonition
definition
- term in admonition with
code
and bold definition
link: term in admonition
Topic
- term in topic
definition
- term in topic with
code
and bold definition
link: term in topic
link: term in sidebar
Field Lists§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-field-lists
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists
- Date
2001-08-16
- Version
1
- Authors
Me
Myself
I
- Indentation
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.
- Parameter i
integer
Admonition
- field
value
Topic
- field
value
Option Lists§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists
- -a
Output all.
- -b
Output both (this description is quite long).
- -c arg
Output just arg.
- --long
Output all day long.
- -p
This option has two paragraphs in the description. This is the first.
This is the second. Blank lines may be omitted between options (as above) or left in (as here and below).
- --very-long-option
A VMS-style option. Note the adjustment for the required two spaces.
- --an-even-longer-option
The description can also start on the next line.
- -2, --two
This option has two variants.
- -f FILE, --file=FILE
These two options are synonyms; both have arguments.
- /V
A VMS/DOS-style option.
Admonition
- --flag
Description.
Topic
- --flag
Description.
Quotes§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks
Block Quotes§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes
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:
Unindented paragraph. Block quote 1. --Attribution 1 Block quote 2.Empty comments may be used to explicitly terminate preceding constructs that would otherwise consume a block quote:
* List item. .. Block quote 3.Empty comments may also be used to separate block quotes:
Block quote 4. .. Block quote 5.Blank lines are required before and after a block quote, but these blank lines are not included as part of the block quote.
—
docutils
documentation
Block quote in topic
Block quote.
Note
Block quote in an admonition.
Epigraphs§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph
An epigraph is an apposite (suitable, apt, or pertinent) short inscription, often a quotation or poem, at the beginning of a document or section.
—
docutils
documentation
Highlights§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights
summarize the main points of a document or section
often consisting of a list
Pull-Quotes§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote
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.
—
docutils
documentation
Tables§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#tables
Grid Tables§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables
Header row, column 1 (header rows optional) |
Header 2 |
Header 3 |
Header 4 |
---|---|---|---|
body row 1, column 1 |
column 2 |
column 3 |
column 4 |
body row 2 |
Cells may span columns. |
||
body row 3 |
Cells may span rows. |
|
|
body row 4 |
Simple Tables§
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables
A |
B |
A and B |
---|---|---|
False |
False |
False |
True |
False |
False |
False |
True |
False |
True |
True |
True |
With column spans:
Inputs |
Output |
|
---|---|---|
A |
B |
A or B |
False |
False |
False |
True |
False |
True |
False |
True |
True |
True |
True |
True |
With more complicated stuff:
col 1 |
col 2 |
---|---|
1 |
Second column of row 1. |
2 |
Second column of row 2. Second line of paragraph. |
3 |
|
Row 4; column 1 will be empty. |
|
5 |
Second column of row 5.
Text after bullet. |
6 |
Numbered list:
|
Adjacent tables (is there a vertical space between them?):
col 1 |
col 2 |
col 1 |
col 2 |
CSV Tables§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
Treat |
Quantity |
Description |
---|---|---|
Albatross |
2.99 |
On a stick! |
Crunchy Frog |
1.49 |
If we took the bones out, it wouldn’t be crunchy, now would it? |
Gannet Ripple |
1.99 |
On a stick! |
List Tables§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table
Treat |
Quantity |
Description |
---|---|---|
Albatross |
2.99 |
On a stick! |
Crunchy Frog |
1.49 |
If we took the bones out, it wouldn’t be crunchy, now would it? |
Gannet Ripple |
1.99 |
On a stick! |
Nesting§
Table in admonition
Header with |
---|
Text with |
Table in topic
Header with |
---|
Text with |
Math§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#math
Inline: \(a^2 + b^2 = c^2\)
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#math
Block:
Another block:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-math-domain
With label (since Sphinx 1.8):
Euler’s identity, equation (9.1), was elected one of the most beautiful mathematical formulas.
API Documentation§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html
Info Field Lists§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
A link: send_message()
.
-
send_message
(sender, recipient, message_body[, priority=1])§ Send a message to a recipient
- Parameters
sender (str) – The person sending the message
recipient (str) – The recipient of the message
message_body (str) – The body of the message
priority (integer or None) – The priority of the message, can be a number 1-5
- Returns
the message id
- Return type
int
- Raises
ValueError – if the message_body exceeds 160 characters
TypeError – if the message_body is not a basestring
Python§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain
-
require
(name)§ Hypothetical built-in function.
A link: hello_world()
.
-
my_module.
hello_world
([repeat=1])§ Greet the world.
-
my_module.
__name__
§ Name of the module.
-
exception
my_module.
MyException
(msg[, severity=7])§ A bad thing happened.
-
class
my_module.
MyClass
§ A useful class.
-
enable
(ignore_errors=False)§ Switch it on.
-
static
from_file
(filename)§ Create class instance from file.
-
classmethod
whatever
(arg)§ Nobody knows what that does.
-
data
§ Where all the important stuff is stored
-
@
decorate
§ Apply festive attire.
-
-
@
my_module.
decorate
§ Make it more cozy.
-
my_module.
compile
(source: string, filename, symbol='file') → ast object§ Do some compilation.
C§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-c-domain
-
PyObject *
PyTypeObject
.
tp_bases
§ Base classes.
-
void *
ptr
§ A pointer.
-
PyObject *
PyType_GenericAlloc
(PyTypeObject *type, Py_ssize_t nitems)§ Allocate stuff.
-
DEBUG
§ Show a debugging message.
-
type
MyStruct
§ An opaque struct.
C++§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cpp-domain
-
class
MyBase
§ A base class.
-
class
my_namespace
::
MyClass
§ A class in a namespace.
-
template<typename
T
, std::size_tN
>
classstd
::
array
§ A class template.
-
template<>
classstd
::
array
<bool, 256>§ Full specialization.
-
bool
my_method
(int arg1, std::string arg2)§ A function with parameters and types.
-
bool
my_method
(int, double)§ A function with unnamed parameters.
-
operator bool
() const§ A casting operator.
-
constexpr void
foo
(std::string &bar[2]) noexcept§ A constexpr function.
-
template<>
voidprint
(int i)§ A specialization thereof.
-
int
a
= 42§
-
typedef std::vector<int>
MyList
§ A typedef-like declaration of a type.
-
type
MyContainer
::
const_iterator
§ Declaration of a type alias with unspecified type.
-
using
MyType
= std::unordered_map<int, std::string>§ Declaration of a type alias.
-
enum
MyEnum
§ An unscoped enum.
-
enum
MySpecificEnum
: long§ An unscoped enum with specified underlying type.
-
enum class
MyScopedEnum
§ A scoped enum.
-
protected enum struct
MyScopedVisibilityEnum
: std::underlying_type<MySpecificEnum>::type§ A scoped enum with non-default visibility, and with a specified underlying type.
-
union
MyUnion
§
-
template<typename
It
>
conceptstd
::
Iterator
§ Proxy to an element of a notional sequence that can be compared, indirected, or incremented.
Notation
Valid Expressions
Explicit ref: Data::[anonymous]::a
. Short-hand ref: Data::a
.
-
void
f
(auto &&arg)§ A function template with a single unconstrained template parameter.
-
void
f
(std::Iterator it)§ A function template with a single template parameter, constrained by the Iterator concept.
-
std::Iterator{
It
}
voidadvance
(It &it)§ A function template with a template parameter constrained to be an Iterator.
-
std::LessThanComparable{
T
}
classMySortedContainer
§ A class template with a template parameter constrained to be LessThanComparable.
An expression: a * f(a)
(or as text: a * f(a)).
A type: const MySortedContainer<int>&
(or as text const MySortedContainer<int>&).
JavaScript§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-javascript-domain
-
$.
getJSON
(href, callback[, errback])§ - Arguments
href (string) – An URI to the location of the resource.
callback – Gets called with the object.
errback – Gets called in case the request fails. And a lot of other text so we need multiple lines.
- Throws
SomeError – For whatever reason in that case.
- Returns
Something.
-
class
jsmodule.
MyAnimal
(name[, age])§ - Arguments
name (string) – The name of the animal
age (number) – an optional age for the animal
-
jsmodule.
jsdata
§
-
jsobject.
name
§
reStructuredText§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-restructuredtext-domain
-
.. foo::
§ Foo description.
-
.. bar::
baz
§ Bar description.
-
:foo:
§ Foo description.
The Standard Domain§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain
Program Options§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option
A link: rm -r
.
-
-r
§
Work recursively.
Environment Variables§
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar
A link: ENV_VAR
.
-
ENV_VAR
§ Description of environment variable.
Generic Objects§
-
PAPER
You can set this variable to select a paper size.
-
SCISSORS
Destroys the aforementioned object.
Some text before the first section title.
Sections§
Header Level 2§
Header Level 3§
Header Level 4§
Header Level 5§
Only levels down to <h6>
are typically supported.
Header Level 2§
Text.
Rubric§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric
Some text.
Title of the Rubric
Some text.
Note
Some text.
Rubric in admonition
Some text.
Topic
Some text.
Rubric in topic
Some text.
(Local) Table of Contents§
https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
Nested toctree
§
Nested Document With a Very, Very, Very, Very, Very, Very, Very Long Title§
This is a nested document.
Some text before section title.
Further<br>Nested”Document§
This is a nested document within a nested document.
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
.
Another Top-Level Section§
It is uncommon – and a bit weird – to have multiple top-level sections in the same source file.
Page Without Sidebar§
This page has no sidebar,
because an empty list of sidebar templates was chosen for
html_sidebars
in conf.py
:
56 57 58 59 60 61 62 63 64 | html_sidebars = {
'**': [
'github-badge.html', # Custom template, see _templates/
'globaltoc.html',
'separator.html',
'indices.html',
],
'showcase/no-sidebar': [], # To demonstrate a page without a sidebar
}
|
If you don’t want to show the sidebar at all,
you can disable it globally with the theme option nosidebar
.