Depending on how you want to use the theme and its extensions, use one of the following methods to install the Sphinx awesome theme.
On this page
You can install a released version from the Python Package Index (PyPI):
$ pip install sphinxawesome-theme
You can also install the latest development version of the theme directly from GitHub:
$ pip install git+https://github.com/kai687/sphinxawesome-theme.git
If you want to use a modified version of the theme, you can load the theme from a local Python package. This doesn’t require any special configuration, but can be slower initially, since you need to rebuild and reinstall the local package after each modification.
Build the theme as a Python package.shell
$ poetry build
This command creates a new directory
dist/containing the source distribution in
.tar.bz2format and as wheel in a
In your project, install the theme from the locally built package.shell
$ pip install /path/to/sphinxawesome_theme/dist/sphinxawesome_theme-*-py3-none-any.whl
This command installs the pre-built package in the current environment.
The project has two different sets of dependencies. If you want to write documentation, write tests, or modify the Python extensions, install the Python dependencies. See Install Python dependencies for more information.
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. See Fork a repo in the GitHub documentation for more information.
Clone the (forked) repository.
If you forked the repository, enter:
$ git clone https://github.com/YOUR_GITHUB_USERNAME/sphinxawesome-theme.git
YOUR_GITHUB_USERNAMEwith your user name on GitHub. If you didn’t fork the repository, clone the original repository:shell
$ git clone https://github.com/kai687/sphinxawesome-theme.git
See Cloning a repository in the GitHub documentation for more information.
Follow these steps to install the Python dependencies:
Install Poetry and Nox.
Follow the recommended steps for how to install Poetry. 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 dependencies.shell
$ poetry install
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
$ nox -ls
noxwithout any option to run the default sessions, such as building the docs, testing, and linting.
To build the documentation, for example, with Python 3.9:shell
$ nox -s docs -p 3.9
Check, if Node.js is installed.shell
$ node --version
If Node.js is installed, this command returns the version number, for example:shell
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/ └...
$ yarn install
Build the theme.shell
$ yarn build