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

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