Contribution guide#

To build the docs#

The Docs are build with Sphinx and Read the Docs. Due to issues with included C programs (GMT and GDAL) in a pip-installed package, PyGMT and GeoPandas aren’t included in the package dependencies, so RTD can’t run the scripts which are part of the docs (i.e. walkthrough.ipynb). Because of this the notebooks don’t execute on a build, as specified by execute_notebooks: 'off' in _config.yml.

Additionally we use Poetry as a package manager, which also can’t include PyGMT or GeoPandas successfully. To get around this, we will export the poetry venv, add PyGMT and Geopandas, run the .ipynb’s for the docs, then build the docs.

Set up a virtual environment#

Set up the poetry virutal environment:

poetry install

Export to a requirements.txt:

poetry export -f requirements.txt --output requirements.txt --dev

Deactivate poetry shell:

deactivate

Install with pip in a conda/mamba env:

mamba create --name antarctic_plots python=3.9
mamba activate antarctic_plots
pip install --no-deps -r requirements.txt

Add PyGMT and GeoPandas:

mamba install pygmt geopandas

Add antarctic_plots in editable mode:

pip install -e .

Run all .ipynb’s to update them#

make run_doc_files

format and check all the code#

make format
make check

Fix issues shown in make check. If lines are too long, split them. If they are urls, and you want flake8 to ignore the line, ad # noqa at the end of the line.

Check the build manually#

make build_docs

This will run the .ipynb files, and convert them to markdown to be included in the dos. Check for returned errors and open index.html in docs/_build/html/ to view the docs.

Automatically build the docs#

Add, commit, and push all changes to Github in a Pull Request, and RTD should automatically build the docs.

To build and publish the package#

Follow all the above instructions for building the docs

Increase the version number in pyproject.toml

Then run the following:

poetry shell
make publish

This will both build the dist files, and upload to PyPI. Now push the changes to Github and make a release with the matching version #.

To update the dependencies#

The package uses Poetry (v.1.1.14) to handle dependencies, build, and publish. Unfortunately, do to PyGMT relying on the C package GMT, poetry can’t install PyGMT. To update any other dependencies, use the below commands:

poetry add <PACKAGE>

or if the package is only for development/documentation

poetry add <PACKAGE> -D

Then:

poetry lock
poetry install

This will solve the dependencies for the added package, re-write the poetry.lock file, and install the new lock file.