Contribution guide
Contents
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.