How to install the theme

Install the theme as a Python package (recommended)

In most use cases, you should install the theme as a Python package. You can make small modifications by adding custom CSS or JavaScript files. See Add or override styles for more information.

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

Check the “HEAD” section at the top of the CHANGELOG file. These features and bugfixes are available in the version on GitHub but not yet in the released version on PyPI.

Install the theme as a local package

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.

1. Create a local copy of the theme

2. Build the theme as a Python package:

   shell

   poetry build
   

   This command creates a new directory dist/ containing the source distribution in .tar.bz2 format and as wheel in a .whl file.

3. 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.

   Tip

   You can also skip the separate build step and install the top level directory:

   shell

   pip install /path/to/sphinxawesome_theme
   

   This command builds and installs the package in one step. It’s a bit slower than the procedure outlined before.

Set up a development environment

The project has two different sets of dependencies, for Python and JavaScript. If you want to write documentation, write tests, or modify the Python extensions, install the Python dependencies. See Install Python dependencies for more information.

If you want to modify the Jinja2 templates1, the CSS, or the JavaScript files, you also need to install the JavaScript dependencies. See {ref}Install JavaScript dependencies for more information.

In both cases, create a local copy first.

Create a local copy of the theme

In order to modify the theme, create a local copy first:

1. 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.

2. Clone the (forked) repository:

   If you forked the repository, enter:

   git clone https://github.com/YOUR_GITHUB_USERNAME/sphinxawesome-theme.git
   

   Replace YOUR_GITHUB_USERNAME with your GitHub username. 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.

Install Python dependencies

The Sphinx awesome theme uses Poetry to manage the Python dependencies. Testing, linting, and building the documentation is handled by Nox.

Follow these steps to install the Python dependencies:

1. 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 -
   

2. 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

3. Install the Python dependencies:

   shell

   poetry install
   

Check Poetry’s documentation for more information.

1. 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
   

1. 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
   

   Enter nox without 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
   

Install JavaScript dependencies

Follow these steps to install the JavaScript dependencies:

1. Check, if Node.js is installed:

   shell

   node --version
   

   If Node.js is installed, this command returns the version number, for example:

   shell

   v14.17.3
   

   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.

2. Optional: install yarn:

   shell

   npm install --global yarn
   

   The awesome theme uses yarn (classic). The dependencies are pinned to the specific versions in the yarn.lock file. If you don’t want to use the same versions of the JavaScript packages, you can use npm as well.

3. Change to the theme-src/ directory:

   shell

   ./sphinxawesome-theme/
      ├src/
      │ ├sphinxawesome_theme/
      │ └theme-src/
      ├docs/
      └...
   

4. Install the JavaScript dependencies:

   shell

   yarn install
   

5. Build the theme:

   shell

   yarn build
   

1

Technically, you only need to add the JavaScript dependencies, if you want to change the CSS classes inside the templates. For example, if you add a utility class that wasn’t previously used, you need to run the JavaScript/CSS pipeline again to include it in the final style sheet.