Configure the theme
Configure the Awesome Theme by changing one of its options.
Theme options
You can configure the theme by modifying the html_theme_options
dictionary in the
Sphinx configuration file conf.py
.
-
If you don’t want to include entries from a hidden toctree directive in the sidebar, set
nav_include_hidden
toFalse
.# This option is `True` by default html_theme_options = {"nav_include_hidden": False}
By default, the
toctree
directive includes your content and generates a list of links in the content area of the page. With thehidden
option, the content is still included, but no links are printed in the main content area.
-
The Awesome Theme shows links to all your documentation pages in sidebar on the left side. If you want to hide the sidebar on all pages, set this option to
False
:
-
show_breadcrumbs
-
The Awesome Theme shows breadcrumbs links at the top of each page To hide the breadcrumbs, set this option to
False
:
-
breadcrumbs_separator
-
To select a different separator for the breadcrumbs navigation links, set:
# The default separator is `/` html_theme_options = {"breadcrumbs_separator": "CHAR"}
Replace
CHAR
with a character or HTML entity of your choice.
-
show_scrolltop
-
To show a button that scrolls to the top of the page when clicked, set this option to
True
:
-
extra_header_links
-
To add extra links to the header of your documentation, set the following option:
# This option is `False` by default html_theme_options = { extra_header_links = { "link1": "/url1", "link2": "/url2", } }
The keys of the
extra_header_links
dictionary are the link texts. The values are absolute URLs.
Extension options
Note
Extension options are only available
if you add the theme to the list of extensions
in your Sphinx configuration:
extensions = ["sphinxawesome_theme"]
The Awesome Theme enables several internal extensions that enhance the user experience.
The following configuration values are set at the top level in the Sphinx
configuration file conf.py
:
-
html_collapsible_definitions
-
Set this option to
True
to make code references, such as classes, methods, and other objects, collapsible and expandable.
-
html_awesome_headerlinks
-
Set this option to
False
to restore Sphinx’s default behavior for headerlinks. In the Awesome Theme, clicking a headerlink copies the URL to the clipboard.
-
html_awesome_code_headers
-
By default, the Awesome Theme shows the programming language of a code block in its header. If you don’t want to show the programming language, set this option to
False
.
-
html_awesome_docsearch
-
Set this option to
True
to use Algolia DocSearch instead of the built-in search.To configure DocSearch, add these environment variables:
DOCSEARCH_APP_ID
The id of your Algolia app
DOCSEARCH_API_KEY
The API key for searching your index on Algolia
DOCSEARCH_INDEX_NAME
The name of your Algolia index for your documentation project.
You can add environment variables with one of these options:
Add them to a
.env
file in your Sphinx project directoryAdd them on the command line before building your documentation
Add them to the
docsearch_config
dictionary in your Sphinx configuration fileconf.py
:
Note
Algolia DocSearch is an external web service. You need to apply and receive your credentials before you can use it.