Load the theme

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

Load the theme from a Python package

To use the Awesome Theme in your documentation:

  1. Install the theme as a Python package (recommended)

  2. Add the html_theme configuration option to your Sphinx configuration file conf.py:

    python File: conf.py
    html_theme = "sphinxawesome_theme"

  3. Add the sphinxawesome_theme as an extension to your Sphinx configuration:

    python File: conf.py
    extensions = ["sphinxawesome_theme"]

    Loading the Awesome Theme as an extension activates the internal Sphinx extensions that enhance the user experience.

    See also

    Extension options

Load the theme from a local directory

If you want to keep your documentation and theme as a single project, you can load the Awesome Theme from a local directory. This can be useful if you want to customize the theme.

Note

When loading the theme from a local directory, you need to manage the dependencies yourself. This theme needs the beautifulsoup package to run. You can install it with pip:

terminal
pip install bs4

Example

The following example assumes you have a Sphinx project with the following structure, and you want to load the theme from the _themes/ folder.

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

To load the theme from a local directory, follow these steps:

  1. Create a local copy of the repository.

  2. Copy the directory sphinxawesome-theme/src/sphinxawesome_theme/ into your Sphinx project:

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

  3. Add the _themes/ directory to the system path in the Sphinx configuration:

    python File: conf.py
    import os
import sys

sys.path.append(os.path.abspath("_themes"))

    Adding this directory makes it discoverable for Sphinx.

  4. Add the _themes/ directory to the exclude_patterns:

    python File: conf.py
    exclude_patterns = ["_themes"]

    This prevents Sphinx from searching the _themes/ directory for documentation files.

  5. Add the theme as an extension and as a theme:

    python File: conf.py
    extensions = ["sphinxawesome_theme"]
html_theme = "sphinxawesome_theme"