Developer Guide¶

Git Workflow¶

You should use a forking workflow to develop wildcat. In brief, you should make a fork of the official repository, and then create merge requests from the fork to the main branch of the official repository. These requests will then be reviewed before merging.

Installation¶

Prerequisites

Wildcat requires Python 3.11+, and these instructions also require git.

We recommend using poetry to install wildcat. This will provide various command line scripts useful for developing the project.

You can install poetry using:

pip install poetry

and read also the poetry documentation for alternative installation instructions.

Next, clone your fork of the project and navigate to the cloned repository. Then, use:

poetry install --with dev

which will install wildcat and various development libraries.

Formatting¶

This project uses isort and black to format the code. You can apply these formatters using:

poe format

This should format the code within the wildcat and tests directories. We also note that many IDEs include tools to automatically apply these formats.

You can also use:

poe lint

to verify that all code is formatted correctly. The Gitlab pipeline requires that this check passes before code can be merged.

Testing¶

This project uses the pytest framework to implement tests. Before adding new code, the Gitlab pipeline requires:

All tests passing, and
100% test coverage

So as a rule, all new code should include accompanying tests. The tests should follow a parallel structure to the wildcat package, and the tests for a given module should be named test_<module>.py or test_<folder>_<module>.py in the case of duplicate module names.

Within a test module, multiple tests for the same function should be grouped into a class. Test class names should use capitalized camel-case. Underscores are discouraged, except when needed to distinguish between public and private routines with the same name. Individual tests should be named using standard Python snakecase (lowercase separated by underscores).

Note that you can check the status of the tests using:

poe tests

Documentation¶

The documentation is built using sphinx with the furo theme. The content is written in reStructuredText Markup (reST). You can find a nice introduction to reST in the sphinx documentation, and the full documentation is here: reST Specification.

The docs use the sphinx_design extension to enable dropdowns and tabbed panels within the content. The final website is deployed using Gitlab Pages via a manual job in the Gitlab pipeline. You must trigger this job manually to deploy new docs.

You can build the docs locally using:

poe docs

This will create the documentation HTML pages within the public folder of the repository. You can open these docs in a browser using:

poe open-docs

Gitlab Pipeline¶

The Gitlab pipeline requires that:

Code dependencies pass a security check,
All code is formatted correctly, and
The tests pass with 100% coverage

You can mimic the pipeline using:

poe pipeline

Scripts¶

Development scripts are available via the poethepoet interface, and are defined in pyproject.toml.

The following table provides a complete list of available scripts:

Script Name	Description
`safety check`	Checks dependencies for security vulnerabilities
`format`	Applies formatters to `wildcat` and `tests`
`lint`	Checks that `wildcat` and `tests` are formatted correctly
`tests`	Runs tests and requires 100% coverage
`docs`	Rebuilds the docs locally
`open-docs`	Opens locally built docs in a web browser
`pipeline`	Mimics the Gitlab pipeline by running the `safety`, `lint`, and `tests` scripts