Install the theme

Depending on how you want to use the theme, install it as a Python package or copy it into a local directory.

On this page

Install the theme as a local package

You can install the theme as a local package. This can be useful if you want to modify the theme and test your local modifications. It can also be useful if you want to keep your documentation and theme separate.

  1. Create a local copy of the theme.

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

    shell
    pip install /path/to/sphinxawesome_theme

    Replace /path/to/sphinxawesome_theme with the path to the directory containing 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, write tests, 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.

Note

It’s best to install the JavaScript dependencies, even if you just want to edit the Jinja2 templates. The theme uses Tailwind CSS and webpack. If you add new classes from Tailwind, you need to run webpack to include them in the output CSS.

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.

  2. Clone the (forked) repository:

    • If you forked the repository, enter:

      shell
      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:

      shell
      git clone https://github.com/kai687/sphinxawesome-theme.git

See also

Clone a repository from GitHub

Install Python dependencies

The Sphinx 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. 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.

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

  5. 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
v14.17.5

    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/
├── tests/
└── ...

  4. Install the JavaScript dependencies:

    shell
    yarn install

  5. Build the theme:

    shell
    yarn build