Contributing

Currently, GridKit is a solo maintained project, but help is most welcome!

Since this is a small project there is no forum or mailing list, but please feel free to start a GitHub issue, pull request or contact me directly on tmillenaar -at- gmail -dot- com. I’d love to get to know anyone interested in the package. I’d also love to learn what others might create with GridKit.

Installing for development

Naturally, you’ll first want to fork or clone the repository.

Note

There are of course many ways of deploying software. In this example I will create a new virtual environment using Python’s ‘venv’ package on an Ubuntu machine

Of course we start by cloning or forking from GitHub.

Then go into the folder and the gridkit-py sub-directory

cd GridKit/gridkit-py

Now let’s create a venv to use.

python3 -m venv gridkit_venv

Activate the venv

source gridkit_venv/bin/activate

Upgrade the basics: pip, setuptools, wheel

python3 -m pip install pip setuptools wheel

Note

When running pip install ., it is assumed that rustup and Cargo are installed. If these are not installed, see the rust installation guide. The build process also assumes build tools are installed such as gcc and make. On Ubuntu, as used for this example, these can be installed using sudo apt install build-essential.

Install the package with the additional ‘doc’ and ‘test’ dependencies. Here the -e flag will make sure the the local files are used. If this flag is omitted, a copy is installed in the venv which will be used over the local files and not reflect any changes you make in the repository.

python3 -m pip install -e .[doc,test]

Since the python code partially uses functions defined in Rust, we have to compile the rust binary. This is done automatically when installing the python package. If changes are made in the rust code (in the ../gridkit-rs directory) the rust binary needs to be re-build for the changes to take effect. Run the following to compile the Rust binary for use in python:

maturin develop --release

The ‘–release’ flag will do some further optimizations. This is optional when testing. The compilation will take slightly longer but the code in the binary will run faster. Either way, the binary will get stored in the gridkit-py/gridkit subfolder and will be called something like ‘gridkit_rs.cpython-310-x86_64-linux-gnu.so’ or your platform equivalent.

Code formatting

black and isort are used for code formatting. These packages are installed when the [test] argument is used during installation (see the command above). Pytest-black will test the format of the python files. Code that does not pass the test should be reformatted using black

python3 -m black gridkit tests/test_gridkit/

and isort

python3 -m isort gridkit tests/test_gridkit/

It is recommended to install the pre-commit hook, which will check the code format on commit and fix it if needed

pre-commit install

This process should take away a lot of strain around neatly formatting the code and ensures the same code standards are enforced all over the codebase.

Running tests and building docs

Now the package is installed, the unittests can be ran by calling pytest

python3 -m pytest tests

Run the doctests

python3 -m pytest gridkit/ --doctest-modules

To build the documentation, a script was created at docs/build_docs/sh. This script can be called like so bash docs/build_docs.sh, note that in order for the script to work you need to use bash and not sh. The script will build documentation for all released versions (after v0.7.0), as well as the head of the main branch. So you can build all docs by running the following from the gridkit-py directory:

bash docs/build_docs.sh

Building the docs for all versions takes a lot of time though, so if you want to iterate quickly it is recommended to do the following:

export GRIDKIT_DOC_BUILD_LATEST_VERSION="dev"
export GRIDKIT_DOC_BUILD_CURRENT_VERSION="dev"
export GRIDKIT_DOC_BUILD_TAGS="['dev']"
python3 -m sphinx.cmd.build docs/source build/sphinx/dev/html

This assumes that you have an environment in which gridkit is installed with the doc dependencies. To install this from a checkout of the repository, run pip install -e ./[doc].

The docs are then stored locally in ./build/sphinx/dev/html/. If you build all the docs using the docs/build_docs.sh script the docs are then stored in ./build/sphinx/html/

Note

Depending on how you installed sphinx, you might also be able to call sphinx-build instead of python3 -m sphinx.cmd.build. Use whatever you like.