Depending on how you want to use the theme, install it as a Python package or copy it into a local directory.
On this page
It’s most convenient to install the theme as a Python package. You can customize the theme by adding styles or extra templates.
To install the latest released version from the Python Package Index PyPI:
pip install sphinxawesome-theme
To install the latest development version of the theme directly from GitHub:
pip install git+https://github.com/kai687/sphinxawesome-theme.git
See the CHANGELOG file for extra features and bugfixes in the development version that aren’t released yet.
You can install the theme as a local package. This can be useful if you want to modify the theme and test your local modifications. It can also be useful if you want to keep your documentation and theme separate.
To install the local version of the theme in your project:shell
pip install /path/to/sphinxawesome_theme
/path/to/sphinxawesome_themewith the path to the directory containing the
In both cases, create a local copy first.
In order to modify the theme, create a local copy first:
Optional: fork the repository.
If you don’t want to merge your changes with the original repository, you can skip this step.
Clone the (forked) repository:
If you forked the repository, enter:shell
git clone https://github.com/GITHUB_USERNAME/sphinxawesome-theme.git
GITHUB_USERNAMEwith your GitHub username.
If you didn’t fork the repository, clone the original repository:shell
git clone https://github.com/kai687/sphinxawesome-theme.git
Follow these steps to install the Python dependencies:
Follow the recommended steps for how to install Poetry.
On macOS and Linux, enter:shell
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -
On Windows PowerShell:Powershell
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
Install Nox via pip:shell
pip install --user --upgrade nox
If you want to use the same version of Poetry and Nox as the original repository, see the versions in the file constraints.txt.
Install the Python dependencies:shell
Check Poetry’s documentation for more information.
Optional: install pre-commit hooks:shell
poetry run pre-commit install
If you don’t plan on committing any changes to the forked repository, you can skip this step. Check the file .pre-commit-config.yaml to see which pre-commit hooks are active.
To test pre-commit in combination with poetry, run:shell
poetry run pre-commit run --all
Run a Nox session.
You can run any Nox session to confirm that the environment is working. To list the available sessions, enter:shell
noxwithout any option to run the default sessions, such as building the docs, testing, and linting.
For example, to build the documentation with Python 3.9, enter:shell
nox -s docs -p 3.9
Check, if Node.js is installed:shell
$ node --version v14.17.5
If the command fails, you may need to install Node.js first, or activate it in your current terminal session. Have a look at the Node Version Manager project for a way to install and manage multiple versions of Node.js.
npm install --global yarn
The awesome theme uses yarn (classic). The dependencies are pinned to the specific versions in the
Change to the
./sphinxawesome-theme/ ├── src/ │ ├── sphinxawesome_theme/ │ └── theme-src/ ├── docs/ ├── tests/ └── ...
Build the theme:shell