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:
Add the
html_theme
configuration option to your Sphinx configuration fileconf.py
:Add the
sphinxawesome_theme
as an extension to your Sphinx configuration:Loading the Awesome Theme as an extension activates the internal Sphinx extensions that enhance the user experience.
See also
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
:
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.
./
├── conf.py
├── index.rst
├── _themes/
└── ...
To load the theme from a local directory, follow these steps:
Copy the directory
sphinxawesome-theme/src/sphinxawesome_theme/
into your Sphinx project:terminalcp -r sphinxawesome-theme/src/sphinxawesome_theme _themes/
Add the
_themes/
directory to the system path in the Sphinx configuration:Adding this directory makes it discoverable for Sphinx.
Add the
_themes/
directory to theexclude_patterns
:This prevents Sphinx from searching the
_themes/
directory for documentation files.Add the theme as an extension and as a theme: