Developer guide

Running the tests

The following will discover and run all unit test:

pip install --upgrade pip
pip install -e .[testing]
pytest -v

You can also run the tests in a virtual environment with tox:

pip install tox tox-conda
tox -e py38 -- -v

Automatic coding style checks

Enable enable automatic checks of code sanity and coding style:

pip install -e .[pre-commit]
pre-commit install

After this, the black formatter, the pylint linter and the pylint code analyzer will run at every commit.

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-diff comes with a .github folder that contains continuous integration tests on every commit using GitHub Actions. It will:

  1. run all tests for the django ORM

  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-diff repository (preferably using aiida-diff as the project name)

The documentation is now available at aiida-diff.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-diff

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).