Contributing as a developer#

Fork the repository

Learn how to fork the project and get your own copy.

Fork the repository
Clone the repository

Download your own copy in your local machine.

Clone the repository
Install for developers

Install the project in editable mode.

Install for developers

Fork the repository#

Forking the repository is the first step for contributing to the project. This allows you to have your own copy of the project so you can make changes without affection the main project. Once you have made your changes, you can submit a pull-request to the main project to have your changes reviewed and merged.

Fork this project

Note

If you are an Ansys employee, you can skip this step.

Clone the repository#

Make sure you configure SSH with your GitHub account. This allows you to clone the repository without having to use tokens or passwords. Also, make sure you have git installed in your machine.

To clone the repository using SSH, run:

git clone git@github.com:ansys/ansys-sphinx-theme

Install for developers#

Installing Ansys sphinx theme in development mode allows you to perform changes to the code and see the changes reflected in your environment without having to reinstall the library every time you make a change.

Virtual environment#

Start by navigating to the project’s root directory by running:

cd ansys-sphinx-theme

Then, create a new virtual environment named .venv to isolate your system’s Python environment by running:

python -m venv .venv

Finally, activate this environment by running:

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

source .venv/bin/activate

Development mode#

Now, install Ansys sphinx theme in editable mode by running:

python -m pip install --editable .

Verify the installation by checking the version of the library:

from ansys_sphinx_theme import __version__
print(f"Ansys sphinx thenme version is {__version__}")

>>> Ansys sphinx theme version is 1.5.2

Install Tox#

Once the project is installed, you can install Tox. This is a cross-platform automation tool. The main advantage of Tox is that it allows you to test your project in different environments and configurations in a temporary and isolated Python virtual environment. To install Tox, run:

python -m pip install tox

Finally, verify the installation by listing all the different environments (automation rules) for Ansys Sphinx theme:

python -m tox list
Default Tox environments

Environment

Description

usage

code-style

check project code style

python -m tox -e code-style

doc-style

Checks project documentation style

python -m tox -e doc-style

doc-links

Checks documentation links and pages generates properly

python -m tox -e doc-links

doc-html

Checks documentation links and pages generates properly

python -m tox -e doc-html

doc-pdf

Checks documentation links and pages generates properly

python -m tox -e doc-pdf

doc-clean

Checks documentation links and pages generates properly

python -m tox -e doc-clean

doc-serve

Checks documentation links and pages generates properly

python -m tox -e doc-serve

dist

Checks project distribution

python -m tox -e dist

Adhere to code style#

Ansys Sphinx theme follows the PEP8 standard as outlined in PEP 8 in the PyAnsys Developer’s Guide and implements style checking using pre-commit.

To ensure your code meets minimum code styling standards, run these commands:

pip install pre-commit
pre-commit run --all-files

or use tox as above:

tox -e code-style

You can also install this as a pre-commit hook by running this command:

pre-commit install

This way, it’s not possible for you to push code that fails the style checks:

$ pre-commit install
$ git commit -am "added my cool feature"
ruff.....................................................................Passed
ruff-format..............................................................Passed
codespell................................................................Passed
prettier.................................................................Passed
check for merge conflicts................................................Passed
debug statements (python)................................................Passed
check yaml...............................................................Passed
trim trailing whitespace.................................................Passed
Validate GitHub Workflows................................................Passed
Add License Headers......................................................Passed

Customize the theme#

Theme configuration is distributed across multiple files for flexibility and modularity.

Customize the SCSS files#

Many styles are defined in SCSS files located in the src/ansys_sphinx_theme/assets/styles/ directory. The primary SCSS files include:

  • ansys-sphinx-theme.scss: Contains the main theme configuration.

  • pydata-sphinx-theme-custom.scss: Contains custom modifications for the PyData theme.

To modify the SCSS files, follow these steps:

  1. Navigate to the src/ansys_sphinx_theme/assets/styles/ directory.

  2. Edit the relevant SCSS files as needed.

  3. Build the library using the following command along with the documentation dependencies:

    python -m pip install -e '.[doc]'

    This command installs the library in editable mode and builds the SCSS files.

Important

The built SCSS files are stored in the src/ansys_sphinx_theme/theme/ansys_sphinx_theme/static/styles/ directory. These files are regenerated during each build process, so avoid editing them directly.

  1. Build the documentation and serve it locally using any of the following commands:

    Linux/macOS/UNIX/Windows

    python -m tox -e doc-serve

    make -C doc serve

    doc\make.bat serve

    Linux/macOS/UNIX/Windows

    stb serve doc/source

    After the build completes, the documentation is served on localhost and automatically opens in the default web browser. SCSS file changes are monitored, and the documentation rebuilds automatically.

Note

To use Tox for building and serving documentation, run the following command:

python -m tox -e doc-serve

This command builds the documentation, opens it in the default browser, and monitors the source files for changes to trigger automatic rebuilds.

Build the documentation#

To build documentation locally, you can either use Tox as mentioned above or run the following commands:

  1. Install the required dependencies by running:

    python -m pip install -e .[doc]

  2. Build the documentation by running:

    # On Linux or macOS
make -C doc/ html

# On Windows
doc\make.bat html

  3. The documentation is built in the doc/_build/html directory. Open the index.html file in your browser to view the documentation.

You can clean the build directory by running:

# On Linux or macOS
make -C doc/ clean

# On Windows
doc\make.bat clean

Note

Use tox -e doc-serve to build the documentation and open it in your default browser. This command will also watch for changes in the source files and rebuild the documentation automatically.