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:

Windows

CMD

.venv\Scripts\activate.bat

PowerShell

.venv\Scripts\Activate.ps1

macOS/Linux/UNIX

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

Build the documentation#

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

Install the required dependencies by running:
```
python -m pip install -e .[doc]
```

Build the documentation by running:

# On Linux or macOS
make -C doc/ html

# On Windows
doc\make.bat html

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