Add the theme

Learn how to add the Awesome Theme to your Sphinx documentation.

Add the theme to your Sphinx configuration

1. Install as a Python package.

2. Add the Awesome Theme as an HTML theme:

   File: conf.py

   html_theme = "sphinxawesome_theme"
   

   See also

   html_theme

3. Optional: load a bundled extension to check if you’re using deprecated options:

   File: conf.py

   extensions += [
      "sphinxawesome.deprecated",
   ]
   

For information about the configuration options, see Configure the theme.

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:

1. Install the beautifulsoup package.

   pip install bs4
   

   If you load the theme from a local directly, you need to manage the theme’s dependencies.

2. Create a local copy of the repository.

3. Create a new directory for themes in your Sphinx project—for example, _themes/:

   ./
   ├── conf.py
   ├── index.rst
   ├── _themes/
   └── ...
   

4. Copy the directory sphinxawesome-theme/src/sphinxawesome_theme/ into the _themes/ directory:

   cp -r sphinxawesome-theme/src/sphinxawesome_theme _themes/
   

5. Update your Sphinx configuration:

   File: conf.py

   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 _themes directory available to Sphinx, adds the Awesome Theme as HTML theme and extension, and excludes the directory from being searched for documentation files.

   Note

   If you load the Awesome Theme via the html_theme_path option, 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.

   See also

   exclude_patterns html_theme_path html_theme extensions