Skip to content

Latest commit

 

History

History
209 lines (142 loc) · 5.89 KB

README.dev.md

File metadata and controls

209 lines (142 loc) · 5.89 KB
Raw

bird_cloud_gnn developer documentation

If you're looking for user documentation, go here.

Development install

# Create a virtual environment, e.g. with
python3 -m venv env

# activate virtual environment
source env/bin/activate

# make sure to have a recent version of pip and setuptools
python3 -m pip install --upgrade pip setuptools

# (from the project root directory)
# install bird_cloud_gnn as an editable package
python3 -m pip install --no-cache-dir --editable .
# install development dependencies
python3 -m pip install --no-cache-dir --editable .[dev]

Afterwards check that the install directory is present in the PATH environment variable.

Running the tests

There are two ways to run tests.

The first way requires an activated virtual environment with the development tools installed:

pytest -v

The second is to use tox, which can be installed separately (e.g. with pip install tox), i.e. not necessarily inside the virtual environment you use for installing bird_cloud_gnn, but then builds the necessary virtual environments itself by simply running:

tox

Testing with tox allows for keeping the testing environment separate from your development environment. The development environment will typically accumulate (old) packages during development that interfere with testing; this problem is avoided by testing with tox.

Test coverage

In addition to just running the tests to see if they pass, they can be used for coverage statistics, i.e. to determine how much of the package's code is actually executed during tests. In an activated virtual environment with the development tools installed, inside the package directory, run:

coverage run

This runs tests and stores the result in a .coverage file. To see the results on the command line, run

coverage report

coverage can also generate output in HTML and other formats; see coverage help for more information.

Running linters locally

For linting we will use prospector and to sort imports we will use isort. Running the linters requires an activated virtual environment with the development tools installed.

# linter
prospector

# recursively check import style for the bird_cloud_gnn module only
isort --check-only bird_cloud_gnn

# recursively check import style for the bird_cloud_gnn module only and show
# any proposed changes as a diff
isort --check-only --diff bird_cloud_gnn

# recursively fix import style for the bird_cloud_gnn module only
isort bird_cloud_gnn

To fix readability of your code style you can use yapf.

Pre-commit

You can enable automatic linting by install pre-commit.

pre-commit install

You can also run the linters with pre-commit run -a.

Generating the API docs

cd docs
make html

The documentation will be in docs/_build/html

If you do not have make use

sphinx-build -b html docs/ docs/_build/html

To find undocumented Python objects run

cd docs
make coverage
cat _build/coverage/python.txt

To test snippets in documentation run

cd docs
make doctest

Making a release

This section describes how to make a release in 3 parts:

  1. preparation
  2. making a release on PyPI
  3. making a release on GitHub

(1/3) Preparation

  1. Update the <CHANGELOG.md> (don't forget to update links at bottom of page)
  2. Verify that the information in CITATION.cff is correct
  3. Make sure the version has been updated in bird_cloud_gnn/__init__.py, setup.cfg, and docs/conf.py
  4. Run the unit tests with pytest -v

(2/3) PyPI

In a new terminal, without an activated virtual environment or an env directory:

# prepare a new directory
cd $(mktemp -d bird_cloud_gnn.XXXXXX)

# fresh git clone ensures the release has the state of origin/main branch
git clone https://github.com/point-cloud-radar/bird-cloud-gnn .

# prepare a clean virtual environment and activate it
python3 -m venv env
source env/bin/activate

# make sure to have a recent version of pip and setuptools
python3 -m pip install --upgrade pip setuptools

# install runtime dependencies and publishing dependencies
python3 -m pip install --no-cache-dir .
python3 -m pip install --no-cache-dir .[publishing]

# clean up any previously generated artefacts
rm -rf bird_cloud_gnn.egg-info
rm -rf dist

# create the source distribution and the wheel
python3 -m build

# upload to test pypi instance (requires credentials)
twine upload -u __token__ -p THETOKEN -r testpypi dist/*

Visit https://test.pypi.org/project/bird_cloud_gnn and verify that your package was uploaded successfully. Keep the terminal open, we'll need it later.

In a new terminal, without an activated virtual environment or an env directory:

cd $(mktemp -d bird_cloud_gnn-test.XXXXXX)

# prepare a clean virtual environment and activate it
python3 -m venv env
source env/bin/activate

# make sure to have a recent version of pip and setuptools
pip install --upgrade pip setuptools

# install from test pypi instance:
python3 -m pip -v install --no-cache-dir \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple bird_cloud_gnn

Check that the package works as it should when installed from pypitest.

Then upload to pypi.org with:

# Back to the first terminal,
# FINAL STEP: upload to PyPI (requires credentials)
twine upload -u __token__ -p THETOKEN dist/*

(3/3) GitHub

Don't forget to also make a release on GitHub. If your repository uses the GitHub-Zenodo integration this will also trigger Zenodo into making a snapshot of your repository and sticking a DOI on it.