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"
    # recommended:
    extensions += ["sphinxawesome_theme.highlighting"]
    

    See also

    html_theme

  3. Recommended: add the bundled extension for better code blocks.

    File: conf.py
    extensions += [
       "sphinxawesome.highlighting",
       # 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:

  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.