Configure the theme
Configure the Awesome Theme.
Note
If you’re not using version 5 of the Awesome Theme, read Configure the theme (version 4).
Bundled extensions
The Awesome Theme bundles two Sphinx extensions that let you enhance your documentation. They’re independent from each other, so you can load them separately or together.
sphinxawesome_theme.docsearch
Replaces the built-in search with Algolia DocSearch for showing instant search results as you type. For more information, see Algolia DocSearch.
sphinxawesome_theme.highlighting
Adds the following highlighting options to Sphinx’s
code-block
directive::emphasize-added: LINES
: highlight lines to be added.:emphasize-removed: LINES
: highlight lines to be removed.:emphasize-text: TEXT
: highlight a placeholder word or phrase.
See also
Note
In version 5, many configuration options changed.
To help you with finding and upgrading deprecated options,
add the sphinxawesome.deprecated
extension.
For more information, see Upgrade to version 5.0
Logos
You can use the html_logo
option to set a path to your logo.
If you’re using a logo that works well in dark mode, you only need to declare one logo.
If you want to use different logos for light and dark mode, add them to your theme options:
Theme options
You can configure the Awesome Theme with the html_theme_options
dictionary.
To benefit from code completion and documentation when editing your Sphinx configuration,
you can use the ThemeOptions
class:
from dataclasses import asdict
from sphinxawesome_theme import ThemeOptions
theme_options = ThemeOptions(
# Add your theme options. For example:
show_breadcrumbs=True,
main_nav_links={"About", "/about"},
)
html_theme_options = asdict(theme_options)
You can still configure the theme using a regular dictionary:
html_theme_options = {
# Add your theme options. For example:
"show_breadcrumbs": True,
"main_nav_links": {
"About": "/about",
}
}
- class ThemeOptions[source]
Helper class for configuring the Awesome Theme.
Each attribute becomes a key in the
html_theme_options
dictionary.- awesome_external_links: bool = False
If
True
, the theme includes an icon after external links and addsrel="nofollow noopener"
to the links’ attributes.
- extra_header_link_icons: dict[str, LinkIcon]
A dictionary with extra icons to include on the right of the search bar.
The keys are labels for the link’s
title
attribute. The values are themselvesLinkIcon
.
If
True
, the theme includes entries from hidden toctree directives in the sidebar.The
toctree
directive generates a list of links on the page where you include it, unless you set the:hidden:
option.This option is inherited from the
basic
theme.
- logo_dark: str | None = None
A path to a logo for the dark mode. If you’re using separate logos for light and dark mode, you must provide both logos.
- logo_light: str | None = None
A path to a logo for the light mode. If you’re using separate logos for light and dark mode, you must provide both logos.
A dictionary with links to include in the site header.
The keys of this dictionary are the labels for the links. The values are absolute or relative URLs.
- show_breadcrumbs: bool = True
If
True
, the theme includes breadcrumbs links on every page except the root page.
LinkIcon
reference
- class LinkIcon(*args, **kwargs)[source]
A link to an external resource, represented by an icon.
Algolia DocSearch
DocSearch provides search for open source projects and technical blogs for free. You can apply and receive your credentials.
To replace the built-in search with DocSearch,
Add the theme to your Sphinx configuration and
add the sphinxawesome_theme.docsearch
extension:
How does DocSearch work?
Algolia indexes your content with a crawler. You’ll add the DocSearch UI component to your layout. Now, on every keystroke, DocSearch looks for matching results on Algolia’s servers and updates the view instantly.
DocSearch credentials
Algolia provides you with three credentials for DocSearch. You must add the application ID and search API key to your site to authenticate and authorize search requests. Keep the write API key a secret. You can find your credentials in the Algolia dashboard.
- Application ID
The identifier for your project on Algolia. It’s used to route search requests from your site to your Algolia index.
- Search API key
An API key that allows search requests from your site.
- Write API key
An API key that allows writing to your index. Since Algolia indexes your content automatically with a crawler, you don’t have to use this key. Don’t use the write API key in your site.
Configure DocSearch
To configure DocSearch, declare the docsearch_*
options as regular Python variables:
docsearch_app_id = "YOUR_APP_ID"
docsearch_api_key = "YOUR_API_KEY"
docsearch_index_name = "YOUR_INDEX_NAME"
Use environment variables
Instead of exposing your credentials in your Sphinx configuration file,
you can load them from environment variables.
For example, you can store them in a in a .env
file.
To do this, add the python-dotenv
package to your project
and add the following code to your Sphinx configuration:
import os
from python_dotenv import load_dotenv
# Load environment variables from a .env file
load_dotenv()
docsearch_app_id = os.getenv("DOCSEARCH_APP_ID")
docsearch_api_key = os.getenv("DOCSEARCH_API_KEY")
docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME")
In the same directory as your conf.py
file, create a .env
file with these variables:
DOCSEARCH_APP_ID=YOUR_APP_ID
DOCSEARCH_API_KEY=YOUR_API_KEY
DOCSEARCH_INDEX_NAME=YOUR_INDEX_NAME
To avoid uploading this file to your repository,
add .env
to your .gitignore
file.
The DocSearchConfig
helper
To make it easier to configure DocSearch with code completion and hover help,
the Awesome Theme provides a DocSearchConfig
helper class.
If you’re okay with (ab)using Python’s dynamic character,
you can add the following code:
import os
from python_dotenv import load_dotenv
from dataclasses import asdict
from sphinxawesome_theme.docsearch import DocSearchConfig
# This gets you code completion and documentation for your configuration options
config = DocSearchConfig(
docsearch_app_id=os.getenv("DOCSEARCH_APP_ID")
docsearch_api_key=os.getenv("DOCSEARCH_API_KEY")
docsearch_index_name=os.getenv("DOCSEARCH_INDEX_NAME")
)
vars = locals()
for key, value in asdict(config).items():
vars.__setitem__(key, value)
DocSearch configuration options
- docsearch_api_key
Your Algolia DocSearch search API key. (Required)
Caution
Don’t use your write API key.
- docsearch_container
A CSS selector where the DocSearch UI component should be added. The default is:
#docsearch
.
- docsearch_initial_query
A query for an initial search if you want to show search results as soon as the user opens the search menu.
- docsearch_search_parameter
Any Algolia search parameter you want to add.
- docsearch_missing_results_url
If specified, DocSearch adds a message to the “No results found” screen with the link to the URL you specified, for users to report issues with missing search results. You can include the current search query as parameter
${query}
. For example:docsearch_missing_results_url = "https://github.com/example/docs/issues/new?title=${query}"
See also