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 and extension:

   pythonFile: conf.py

   html_theme = "sphinxawesome_theme"
   extensions = ["sphinxawesome_theme"]
   

   See also

   Extension options html_theme extensions

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:

Note

If you load the theme from a local directory, you need to manage the theme’s dependencies. For example, you need to install the beautifulsoup package. To install it, run: pip install bs4.

1. Create a local copy of the repository.

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

   terminal

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

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

   terminal

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

4. Update your Sphinx configuration:

   pythonFile: conf.py

   html_theme = "sphinxawesome_theme"
   html_theme_path = ["_themes"]
   exclude_patterns = ["_themes"]
   extensions = ["sphinxawesome_theme"]
   

   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.

   See also

   exclude_patterns html_theme_path html_theme extensions