Add the theme
Learn how to add the Awesome Theme to your Sphinx documentation.
If you’re not using version 5 of the Awesome Theme, see Add the theme (version 4).
Add the theme to your Sphinx configuration
Add the Awesome Theme as an HTML theme:
html_theme = "sphinxawesome_theme"
Optional: add the bundled extensions.
extensions += [ "sphinxawesome.highlighting", "sphinxawesome.docsearch", # To help you with the upgrade to version 5: # "sphinxawesome.deprecated", ]
Load the theme from a local directory
If you want to load the Awesome Theme from a local directory without installing a Python package, follow these steps:
pip install bs4
If you load the theme from a local directly, you need to manage the theme’s dependencies.
Create a new directory for themes in your Sphinx project—for example,
./ ├── conf.py ├── index.rst ├── _themes/ └── ...
Copy the directory
cp -r sphinxawesome-theme/src/sphinxawesome_theme _themes/
Update your Sphinx configuration:
import os import sys sys.path.insert(0, os.path.abspath("_themes")) html_theme = "sphinxawesome_theme" extensions = ["sphinxawesome_theme"] html_theme_path = ["_themes"] exclude_patterns = ["_themes"]
This configuration makes the local
_themesdirectory available to Sphinx, adds the Awesome Theme as HTML theme and extension, and excludes the directory from being searched for documentation files.
If you load the Awesome Theme via the
html_theme_pathoption, you must add it as extension and theme. That’s because the Awesome Theme depends on a setup function that only runs when you import the theme as Python code.