This README provides info about the development process.

For more info about the package itself see package README or docs.

If you just want to try it out and don't care about polluting your environment:

We are using conda for environment management (but you can as well use any other tool, e.g. pyenv + venv). The major reason is that conda lets you specify python version and will install that version in the environment. This ensures consistency between different instances (developers, CI, deployment).

The first step is of course to install conda.

To create an environment, run from project root:

And then activate it by:

Creating the environment is performed only once, but you need to activate it every time you start a new shell.

If the configuration file environment.yaml changes, you can update the environment by:

We are using poetry to manage our package and its dependencies. You need to have it installed outside our environment (I recommend to use pipx for that).

To install the package, you need to cd into kilroyplot directory and run:

This will download and install all package dependencies (including development ones) and install the package in editable mode into the activated environment.

Editable mode means that you don't have to reinstall the package if you change something in the code. The changes are reflected automatically.

However, you need to install the package again if you change something in its configuration (e.g. add a new dependency). But more on that later.

If it's the first time installing the package, poetry will write specific versions of all packages to poetry.lock file. This file should be committed to the repository, so other people can have the exact same versions of all dependencies. It will work because poetry install checks if poetry.lock file is available and uses it if it is.

We are using pytest for tests. It's already installed in the environment, because it's a development-time dependency. To start first write the tests and put them in kilroyplot/tests.

To execute the tests, cd into kilroyplot and run:

We are using mkdocs with material for building the docs. It lets you write the docs in Markdown format and creates a nice webpage for them.

Docs should be placed in kilroyplot/docs/docs. They are pretty straightforward to write.

To build and serve the docs, cd into kilroyplot and run:

It will generate site directory with the webpage source and serve it.

If you need to add a new dependency, look into pyproject.toml file. Add it to tool.poetry.dependencies section. If it is a development-time dependency you need to mark it as optional and add it to the right groups in tool.poetry.extras.

After that update the installation by running from kilroyplot directory:

This will install anything new in your environment and update the poetry.lock file. Other people only need to run poetry install to adjust to the incoming changes in the poetry.lock file.

When you push changes to remote, different GitHub Actions run to ensure project consistency. There are defined workflows for:

• deploying docs to GitHub Pages
• testing on different platforms
• drafting release notes
• uploading releases to PyPI

For more info see the files in .github/workflows directory and Actions tab on GitHub.

Generally if you see a red mark next to your commit on GitHub or a failing status on badges in README it means the commit broke something (or workflows themselves are broken).

Every time you merge a pull request into main, a draft release is automatically updated, adding the pull request to changelog. Changes can be categorized by using labels. You can configure that in .github/release-drafter.yaml file.

Every time you publish a release the package is uploaded to PyPI with version taken from release tag (you should store your PyPI token in PYPI_TOKEN secret).

You can use jupyter to experiment with the code and make some great visualizations or reports.

To launch jupyter lab environment, cd into kilroyplot and run:

The developed package is installed in the environment, so we can import it in the notebooks as any other package.