Contributing

General guidelines

Overall guidance on contributing to a PyAnsys library appears in the Contributing topic in the PyAnsys Developer’s Guide. Ensure that you are thoroughly familiar with this guide before attempting to contribute to the grantami-recordlists repository.

The following contribution information is specific to the grantami-recordlists repository, which is for the PyGranta RecordLists library. This PyAnsys library name is often used in place of the repository name to provide clarity and improve readability.

Post issues

Use the Issues page for this repository to submit questions, report bugs, and request new features.

To reach the PyAnsys core team, email pyansys.core@ansys.com.

Developer environment setup

The project uses poetry for packaging and dependency management. See the poetry documentation for installation instructions.

Clone the source repository

Run the following code to clone and install the latest version of the grantami-recordlists repository. It installs the package in editable mode, which ensures changes to the code are immediately visible in the environment. It also installs the required development dependencies to run the tests, build the docs and build the package.

git clone https://github.com/ansys/grantami-recordlists
cd grantami-recordlists
poetry install --with build,doc,tests

Additional tools

Pre-commit

The style checks take advantage of pre-commit. Developers are not forced but encouraged to install this tool via:

python -m pip install pre-commit && pre-commit install

Tox

Tests can be run using tox. The project defines the tox environments in tox.ini. The following tox environments are provided:

• tox -e style: checks for coding style quality.

• tox -e tests: runs all tests and checks code coverage (see Server access for requirements).

• tox -e doc: checks the documentation building process.

Optionally add the -- -m "not integration" suffix to the commands above to skip integration tests. For example, tox -e tests -- -m "not integration" will only run tests that do not require a Granta MI instance.

Server access

Running integration tests and building the examples requires access to a valid Granta MI instance (see Ansys software requirements).

External contributors may not have an instance of Granta MI at their disposal. Prior to creating a pull request with the desired changes, they should make sure that unit tests pass (Tox), static code validation and styling pass (pre-commit), and that the documentation can be generated successfully without the examples (Documenting).

Continuous Integration (CI) on GitHub is configured to run the integration tests and generate the full documentation on creation and updates of pull requests. CI is not configured to run for pull requests from forks. External contributions require approval from a maintainer for checks to run.

Code formatting and styling

This project adheres with PyAnsys recommendation of styling and formatting. The easiest way to validate changes are compliant is to run the following command:

pre-commit run --all-files

Documenting

As per PyAnsys guidelines, the documentation is generated using Sphinx.

For building documentation, use the Sphinx Makefile:

make -C doc/ html && your_browser_name doc/build/html/index.html

If any changes have been made to the documentation, it is strongly recommended to run sphinx directly with the following extra arguments. They ensure all references are valid, and turn warnings into errors. CI uses the same configuration, so it is advised to resolve any warnings/errors locally before pushing changes.

sphinx-build -b html source build -W -n --keep-going

Example notebooks

Examples are included in the documentation to give you more context around the core capabilities described in API reference. Additional examples are welcomed, especially if they cover a key use case of the package that has not yet been covered.

The example scripts are placed in the examples directory and are included in the documentation build if the environment variable BUILD_EXAMPLES is set to True. Otherwise, a different set of examples is run to validate the process.

Examples are checked in as scripts using the light format, see jupytext for more information. As part of the doc build process, the Python files are converted back into Jupyter notebooks and the output cells are populated by running the notebooks against a Granta MI instance.

This conversion between Jupyter notebooks and Python files is performed by nb-convert. For installation instructions, see the nb-convert documentation.