Developer guide

Getting started

We recommend installing poetry for dependency management when developing for aiida-mlip.

This provides a number of useful features, including:

  • Dependency management (poetry [add,update,remove] etc.) and organization (groups)

  • Storing the versions of all installations in a poetry.lock file, for reproducible builds

  • Improved dependency resolution

  • Virtual environment management (optional)

  • Building and publishing tools

Dependencies useful for development can then be installed by running:

poetry install --with pre-commit,dev,docs

Running the tests

Packages in the dev dependency group allow tests to be run locally using pytest, by running:: pytest -v Alternatively, tests can be run in separate virtual environments using tox:: tox run -e ALL This will run all unit tests for multiple versions of Python, in addition to testing that the pre-commit passes, and that documentation builds, mirroring the automated tests on GitHub. Individual components of the tox test suite can also be run separately, such as running only running the unit tests with Python 3.9:

tox run -e py39

See the tox documentation for further options.

Automatic coding style checks

Packages in the pre-commit dependency group allow automatic code formatting and linting on every commit.

To set this up, run:

pre-commit install

After this, the ruff linter, ruff formatter, and numpydoc (docstring style validator), will run before every commit.

Rules enforced by ruff are currently set up to be comparable to:

The full set of ruff rules are specified by the [tool.ruff] sections of pyproject.toml.

If you ever need to skip these pre-commit hooks, just use:

git commit -n

You should also keep the pre-commit hooks up to date periodically, with:

pre-commit autoupdate

Or consider using pre-commit.ci.

Continuous integration

aiida-mlip comes with a .github folder that contains continuous integration tests on every commit using GitHub Actions. It will:

  1. run all tests

  2. build the documentation

  3. check coding style and version number (not required to pass by default)

Building the documentation

  1. Install the docs extra:

    pip install -e .[docs]

  2. Edit the individual documentation pages:

    docs/source/index.rst
docs/source/developer_guide/index.rst
docs/source/user_guide/index.rst
docs/source/user_guide/get_started.rst
docs/source/user_guide/tutorial.rst

  3. Use Sphinx to generate the html documentation:

    cd docs
make

Check the result by opening build/html/index.html in your browser.

Publishing the documentation

Once you’re happy with your documentation, it’s easy to host it online on ReadTheDocs:

  1. Create an account on ReadTheDocs

  2. Import your aiida-mlip repository (preferably using aiida-mlip as the project name)

The documentation is now available at aiida-mlip.readthedocs.io.

PyPI release

Your plugin is ready to be uploaded to the Python Package Index. Just register for an account and use flit:

pip install flit
flit publish

After this, you (and everyone else) should be able to:

pip install aiida-mlip

You can also enable automatic deployment of git tags to the python package index: simply generate a PyPI API token for your PyPI account and add it as a secret to your GitHub repository under the name pypi_token (Go to Settings -> Secrets).