Install the theme

Install the Awesome Theme as a Python package, copy it into a local directory, or install the development dependencies to create your own theme.

Install the theme from a local folder

If you want to modify the theme, you can clone the repository and install the cloned version as 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 --editable /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). 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 modify 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 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

See also

Clone a repository from GitHub

Install Python dependencies

The Awesome Theme uses Poetry to manage the Python dependencies and Nox to test and lint the code.

Note

The commands below install the latest versions of Nox and Poetry. In case of a version conflict, see the file constraints.txt for the version numbers used when building the Awesome Theme Python package.

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

  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.

    Note

    For installing and managing Node.js versions, see these projects:

  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