Install the theme

Install the Awesome Theme as a Python package, copy it into a local directory, or install a full development environment.

Install the theme as a Python package (recommended)

Install the latest released version from the Python Package Index PyPI:

terminal

pip install sphinxawesome-theme

To install the latest development version, run:

terminal

pip install git+https://github.com/kai687/sphinxawesome-theme.git

See the CHANGELOG file for extra features and updates in the development version that aren’t released yet.

If you want to add styles or extra templates, see customize the theme.

Install the theme from a local directory

If you want to customize the theme, you can clone the repository and install the cloned version as a local Python package.

Create a local copy of the repository.
Install the local copy of the theme in your project:
terminal
```
pip install --editable /path/to/sphinxawesome_theme
```
Replace /path/to/sphinxawesome_theme with the path to your local copy of the theme (the directory with the pyproject.toml file). The --editable option installs the package in editable, or development, mode.

Set up a development environment

The project has both Python and JavaScript dependencies. If you want to write documentation or modify the Python extensions, install the Python dependencies.

If you want to edit the Jinja2 templates, the CSS, or the JavaScript files, you also need to install the JavaScript dependencies.

Note

Because this theme uses Tailwind CSS to apply styles, you need to build the theme when you make modifications to the styles. It’s best to install the JavaScript dependencies, even if you just want to edit the HTML templates.

Create a local copy of the repository

Optional: fork the repository.

If you don’t want to merge your changes with the original repository, you can skip this step.
Clone the repository:
- If you forked the repository, run:
  terminal
```
git clone https://github.com/GITHUB_USERNAME/sphinxawesome-theme.git
```
  Replace GITHUB_USERNAME with your GitHub username.
- If you didn’t fork the repository, clone the original repository:
  terminal
```
git clone https://github.com/kai687/sphinxawesome-theme.git
```

Install Python dependencies

The Awesome Theme uses these Python tools:

Poetry to manage the Python dependencies and building the package
Nox to test and lint the Python code, and to build the docs
Pipx to install Python applications in isolated environments and making them available globally

Note

The commands shown in this section install the latest versions of Nox and Poetry. See the file constraints.txt for the version numbers of Nox and Poetry used for building the Awesome Theme Python package.

Follow these steps to install the Python dependencies:

Create a local copy of the repository
Install pipx:
terminal
```
pip install --user pipx
```
Install Poetry:
terminal
```
pipx install poetry
```
Install Nox:
terminal
```
pipx install nox
```
Install nox-poetry:
terminal
```
pipx inject nox nox-poetry
```
Nox-poetry is a package for using Poetry and Nox together. The nox-poetry package must be installed in the same environment as Nox.
Install the Python dependencies:
terminal
```
poetry install
```
Optional: install and test the pre-commit hooks:
terminal
```
poetry run pre-commit install
```
If you don’t plan on committing any changes to the repository, you can skip this step. You can see the active pre-commit hooks in the file .pre-commit-config.yaml.

To test pre-commit with Poetry, run:
terminal
```
poetry run pre-commit run --all
```
Test your Nox environment.

You can run any Nox session to confirm that the environment is working. To list the available sessions, run:
terminal
```
nox --list-sessions
```
For example, run all default sessions:
terminal
```
nox
```

Using the same versions of the Python packages

The commands in the preceding section install the latest versions of Poetry, Nox, and pipx. If you want to constrain the versions to install, you can use pip’s constraint file.

For example, to install a specific version of pipx, run:

terminal

pip install --user --constraint=constraints.txt pipx

For example, to install a specific version of Nox with pipx, run:

terminal

pipx --pip-args=--constraint=constraints.txt nox

See the file constraints.txt for the version constraints used in the Awesome Theme repository.

Tip

In development environments, you might use the latest versions of packages, while for reproducible results in continuous integration (CI) pipelines, it’s often better to install specific versions of packages.

Install JavaScript dependencies

Confirm that Node.js is installed:
terminal
```
$ node --version
v16.16.0
```
If the preceding command fails, make sure that you installed Node.js. If you installed Node.js, make sure that the path to the node executable is in your PATH environment variable.
Note

For installing and managing Node.js versions, see these projects:
- nvm
- Volta
- asdf
Optional: install yarn:
terminal
```
npm install --global yarn
```
If you want to use the same versions of JavaScript packages as in the Awesome Theme repository, use the Yarn package manager.
Create a local copy of the repository

Go to the theme-src/ directory:

terminal

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

Install the JavaScript dependencies:
terminal
```
yarn install
```
Build the theme:
terminal
```
yarn build
```