Install the theme

Install the theme as a Python package (recommended)

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

pip install sphinxawesome-theme

You can also install the latest development version:

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 as a local Python package

If you want to modify the theme and test your modifications first, you can install the theme as a local Python package.

1. Create a local copy of the theme.

2. To install the local version of the theme in your project:

   terminal

   pip install /path/to/sphinxawesome_theme
   

   Replace /path/to/sphinxawesome_theme with the path to your local directory with the theme (the directory with the pyproject.toml file).

Set up a development environment

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

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

Create a local copy of the theme

To modify the theme, create a local copy:

1. Optional: fork the repository.

   If you don’t want to merge your changes with the original repository, you can skip this step.

2. Clone the repository:

   • If you forked the repository, enter:

     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 Poetry to manage the Python dependencies and Nox to test and lint the code.

Follow these steps to install the Python dependencies:

1. Create a local copy of the theme.

2. Install Poetry.

3. Install Nox:

   terminal

   pip install --user --upgrade nox
   

4. Install the Python dependencies:

   terminal

   poetry install
   

5. 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. The active pre-commit hooks are defined in the file .pre-commit-config.yaml.

   To test pre-commit with Poetry, run:

   terminal

   poetry run pre-commit run --all
   

6. Test your Nox environment.

   You can run any Nox session to confirm that the environment is working. To list the available sessions, enter:

   terminal

   nox -ls
   

   For example, to build the documentation with Python 3.10, enter:

   terminal

   nox -s docs -p 3.10
   

Install JavaScript dependencies

1. Confirm that Node.js is installed:

   text

   $ node --version
   v10.24.1
   

   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.

   To install and manage multiple versions of Node.js, see the Node Version Manager project.

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

3. Create a local copy of the theme.

4. Go to the theme-src/ directory:

   terminal

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

5. Install the JavaScript dependencies:

   terminal

   yarn install
   

6. Build the theme:

   terminal

   yarn build