Configuration
Theme options
The following options can be defined in your project’s conf.py
file, using
the html_theme_options
configuration option.
For example:
html_theme_options = {
'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard
'analytics_anonymize_ip': False,
'logo_only': False,
'prev_next_buttons_location': 'bottom',
'style_external_links': False,
'vcs_pageview_mode': '',
'style_nav_header_background': 'white',
'flyout_display': 'hidden',
'version_selector': True,
'language_selector': True,
# Toc options
'collapse_navigation': True,
'sticky_navigation': True,
'navigation_depth': 4,
'includehidden': True,
'titles_only': False
}
Table of contents options
The following options change how toctree
directives generate
documentation navigation.
With this enabled, navigation entries are not expandable – the
[+]
icons next to each entry are removed.- Type:
boolean
- Default:
True
Note
Setting
collapse_navigation
toFalse
and using a high value fornavigation_depth
on projects with many files and a deep file structure can cause long compilation times and can result in HTML files that are significantly larger in file size.
Scroll the navigation with the main page content as you scroll the page.
- Type:
boolean
- Default:
True
The maximum depth of the table of contents tree. Set this to
-1
to allow unlimited depth.- Type:
integer
- Default:
4
Specifies if the navigation includes hidden table(s) of contents – that is, any
toctree
directive that is marked with the:hidden:
option.- Type:
boolean
- Default:
True
- titles_only
When enabled, page subheadings are not included in the navigation.
- Type:
boolean
- Default:
False
Miscellaneous options
- analytics_id
If specified, Google Analytics’ gtag.js is included in your pages. Set the value to the ID provided to you by google (like
UA-XXXXXXX
orG-XXXXXXXXXX
).- Type:
string
Deprecated since version 3.0.0: The
analytics_id
option is deprecated, use the sphinxcontrib-googleanalytics extension instead.
- analytics_anonymize_ip
Anonymize visitor IP addresses in Google Analytics.
- Type:
boolean
- Default:
False
Deprecated since version 3.0.0: The
analytics_anonymize_ip
option is deprecated, use the sphinxcontrib-googleanalytics extension instead.
- canonical_url
This will specify a canonical URL meta link element to tell search engines which URL should be ranked as the primary URL for your documentation. This is important if you have multiple URLs that your documentation is available through. The URL points to the root path of the documentation and requires a trailing slash.
- Type:
URL
Deprecated since version 0.6.0: Use
html_baseurl
instead.
- display_version
If
True
, the version number is shown at the top of the sidebar.- Type:
boolean
- Default:
False
Deprecated since version 3.0.0: Removed in favor of
version_selector
andlanguage_selector
.
- logo_only
Only display the logo image, do not display the project name at the top of the sidebar
- Type:
boolean
- Default:
False
- prev_next_buttons_location
Location to display Next and Previous buttons. This can be either
bottom
,top
,both
, orNone
.- Type:
string
- Default:
bottom
- style_external_links
Add an icon next to external links.
- Type:
boolean
- Default:
False
- vcs_pageview_mode
Changes how to view files when using
display_github
,display_gitlab
, etc. When using GitHub or GitLab this can be:blob
(default),edit
, orraw
. On Bitbucket, this can be either:view
(default) oredit
.- Type:
string
- Default:
blob
orview
Changes the background of the search area in the navigation bar. The value can be anything valid in a CSS background property.
- Type:
string
- Default:
#2980B9
- flyout_display
Specify how to display the flyout (language and version selector). This can be either
attached
orhidden
.attached
means that it will show the flyout in the bottom of the sidebar. You will need to disable the default Read the Docs flyout in order to not have 2 flyouts showing.- Type:
str
- Default:
hidden
- version_selector
Display a version selector below the title. This feature makes usage of Read the Docs Addons for this, so it’s required the documentation to be hosted on Read the Docs. It only appears when there are more than 1 active version.
- Type:
boolean
- Default:
True
- language_selector
Display a language selector below the title. This feature makes usage of Read the Docs Addons for this, so it’s required the documentation to be served on Read the Docs. It only appears when there is more than 1 active language.
- Type:
boolean
- Default:
True
File-wide metadata
The following options can be used as file-wide metadata:
- github_url
Force the Edit on GitHub button to use the configured URL.
- bitbucket_url
Force the Edit on Bitbucket button to use the configured URL.
- gitlab_url
Force the Edit on GitLab button to use the configured URL.
Other configuration
Adding a logo
Using the Sphinx standard option html_logo
,
you can set an image file to be used as a logo at the top of the sidebar. The
theme option logo_only
also allows for only the logo to be shown
at the top of the sidebar.
Adding custom CSS or Javascript
Adding custom CSS or Javascript can help you alter the look and feel of this theme without forking the theme for local use.
In order to add custom CSS or Javascript without disrupting the existing theme files, you can add files to be included in your documentation output.
How the table of contents displays
Currently the left menu will build based upon any toctree
directives defined
in your source files. It outputs 4 levels of depth by default, to allow for
quick navigation through topics. If no TOC trees are defined, Sphinx’s default
behavior is to use the page headings instead.
It’s important to note that if you don’t follow the same styling for your reST headings across your documents, the TOC tree will build incorrectly, and the resulting menu might not show the correct depth when it renders.
Also note that by default the table of contents is set with
includehidden=True
. This allows you to set a hidden TOC in your index file
with the :hidden: property that will allow you
to build a TOC without it rendering in your index.
By default, the navigation will “stick” to the screen as you scroll. However if
your TOC is not tall enough, it will revert to static positioning. To disable the
sticky navigation altogether, change the sticky_navigation
theme option.