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:
pip install sphinxawesome-theme
To install the latest development version, run:
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.
Install the local copy of the theme in your project:terminal
pip install --editable /path/to/sphinxawesome_theme
/path/to/sphinxawesome_themewith the path to your local copy of the theme (the directory with the
--editableoption installs the package in editable, or development, mode.
Set up a development environment
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
GITHUB_USERNAMEwith 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
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:
pip install --user pipx
pipx install poetry
pipx install nox
pipx inject nox nox-poetry
Nox-poetry is a package for using Poetry and Nox together. The
nox-poetrypackage must be installed in the same environment as Nox.
Install the Python dependencies:terminal
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
For example, run all default sessions:terminal
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:
pip install --user --constraint=constraints.txt pipx
For example, to install a specific version of Nox with pipx, run:
pipx --pip-args=--constraint=constraints.txt nox
See the file constraints.txt for the version constraints used in the Awesome Theme repository.
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.
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
nodeexecutable is in your
npm install --global yarn
Go to the
./sphinxawesome-theme/ ├── src/ │ ├── sphinxawesome_theme/ │ └── theme-src/ ├── docs/ ├── tests/ └── ...
Build the theme:terminal