Contribution guide#

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 Read the Docs can’t run the scripts which are part of the docs (i.e. the gallery examples). 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 (since it installs with Pip). To get around this, we will export the poetry venv, add PyGMT and Geopandas independently, run the .ipynb’s for the docs, then build the docs.

Set up a virtual environment#

Set up the poetry virtual environment:

make poetry_env_dev

This solves the dependencies for the packages listed in pyproject.toml, adds the versions to a .lock file, install them in a poetry virtual environment, and exports the resulting environment to a requirements.txt file.

Next we need to create a conda/mamba env: make delete_env make new_env

This will create a new conda env antarctic_plots_dev and install PyGMT.

Activate it and install the package requirements and local antarctic_plots package in editable mode:

mamba activate antarctic_plots_dev
make install_reqs

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, add # 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 docs. 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.

Build and publish the package#

Follow all the above instructions for building the docs

Increase the version number in pyproject.toml

Recreat the poetry environement without the dev packages:

make poetry_env

Then run the following:

make test_publish

This will both build the dist files, and upload to TestPyPI.

Make a new environment, activate it:

mamba create --name antarctic_plots_test python=3.9 pygmt=0.7.0 geopandas=0.11.0
mamba activate antarctic_plots_test

and run the following, replacing the asterisks with the version number:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ antarctic-plots==******

Run a few gallery examples to make sure this env works, then its read to publish to the real PyPI:

make publish

Now push the changes to Github and make a release with the matching version number.

Update the dependencies#

The package uses Poetry (v.1.1.14) to handle dependencies, build, and publish. Unfortunately, due to PyGMT relying on the C package GMT, poetry can’t install PyGMT. This is the same with GeoPandas relygin on GDAL. 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 run through the commands at the top of this page again to update the environement.

If you add a dependency, make sure to include it in the Binder config file. See below.

Set up the binder configuration#

To run examples online, Read the Docs will automatically create a Binder instance for this package. The configuration file is /binder/environment.yml. To create this or update it do the following:

make binder_yaml

This will create an environment with the core dependencies, and export it to a .yml. Open this file and add the following at the bottom of the list of dependencies:

  • pip

  • pip: –ignore-installed –no-deps git+https://github.com/mdtanker/antarctic_plots.git@main

Now, when submitting a PR, RTD will automatically build the docs and update the Binder environement.