MoaceanParcels Package Development
The MoaceanParcels package (moacean_parcels) contains shared kernels and other code for OceanParcels developed by the UBC-MOAD group.
Python Versions
The moacean_parcels package is developed and tested using Python 3.10.
Getting the Code
Clone the code and documentation repository from GitHub with:
$ git clone git@github.com:UBC-MOAD/MoaceanParcels.git
or copy the URI (the stuff after git clone above) from the Code button on the repository page.
Note
The git clone command above assumes that your are connecting to GitHub using SSH. If it fails, please follow the instructions in our Secure Remote Access docs to set up your SSH keys and Copy Your Public ssh Key to GitHub.
Development Environment
Setting up an isolated development environment using Conda is recommended. Assuming that you have Miniconda3 installed, you can create and activate an environment called moacean-parcels that will have all of the Python packages necessary for development, testing, and building the documentation with the commands below.
$ cd MoaceanParcels
$ conda env create -f envs/environment-dev.yaml
$ conda activate moacean-parcels
MoaceanParcels
is installed in editable install mode as part of the conda environment
creation process.
That means that the package is installed in a way that it can be updated when new features are
pushed to GitHub by simply doing a git pull in the MoaceanParcels
directory.
To deactivate the environment use:
(moacean-parcels)$ conda deactivate
Coding Style
The MoaceanParcels package uses Git pre-commit hooks managed by pre-commit to maintain consistent code style and and other aspects of code, docs, and repo QA.
To install the pre-commit hooks in a newly cloned repo, activate the conda development environment, and run pre-commit install:
$ cd MoaceanParcels
$ conda activate moacean-parcels
(moacean-parcels)$ pre-commit install
Note
You only need to install the hooks once immediately after you make a new clone of the MoaceanParcels repository and build your Development Environment.
Building the Documentation
The documentation for the MoaceanParcels package is written in
reStructuredText and converted to HTML using Sphinx.
Creating a Development Environment as described above
includes the installation of Sphinx.
Building the documentation is driven by the docs/Makefile
.
With your moacean-parcels development environment activated,
use:
(moacean-parcels)$ (cd docs && make clean html)
to do a clean build of the documentation. The output looks something like:
Removing everything under '_build'...
Running Sphinx v4.3.1
making output directory... done
loading intersphinx inventory from https://ubc-moad-docs.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://numpy.org/doc/stable/objects.inv...
loading intersphinx inventory from https://oceanparcels.org/gh-pages/html/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 9 source files that are out of date
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] pkg_development
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] pkg_development
generating indices... genindex py-modindex done
copying notebooks ... [100%] kernels/kernel_example_notebooks/recovery_kernels/DeleteParticle-example.ipynb
highlighting module code... [100%] moacean_parcels.kernels.DeleteParticle
writing additional pages... search done
copying images... [100%] _build/doctrees/nbsphinx/kernels_kernel_example_notebooks_recovery_kernels_DeleteParticle-example_13_0.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in _build/html.
The HTML rendering of the docs ends up in docs/_build/html/
.
You can open the index.html
file in that directory tree in your browser
to preview the results of the build.
If you use Firefox,
you can probably accomplish that with:
(moacean-parcels)$ firefox docs/_build/html/index.html
If you have write access to the repository on GitHub, whenever you push changes to GitHub the documentation is automatically re-built and rendered at https://moaceanparcels.readthedocs.io/en/latest/.
Link Checking the Documentation
Sphinx also provides a link checker utility which can be run to find broken or redirected links in the docs. With your moacean-parcels) environment activated, use:
(moacean-parcels))$ cd MoaceanParcels/docs/
(moacean-parcels)) docs$ make linkcheck
The output looks something like:
Running Sphinx v4.2.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [linkcheck]: targets for 2 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] pkg_development
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] pkg_development
( pkg_development: line 20) ok https://black.readthedocs.io/en/stable/
( pkg_development: line 261) ok https://coverage.readthedocs.io/en/latest/
( pkg_development: line 20) ok https://docs.python.org/3.10/
( pkg_development: line 62) ok https://docs.python.org/3/reference/lexical_analysis.html#f-strings
( pkg_development: line 241) ok https://docs.pytest.org/en/latest/
( pkg_development: line 298) ok https://git-scm.com/
( pkg_development: line 106) ok https://conda.io/en/latest/
( pkg_development: line 106) ok https://docs.conda.io/en/latest/miniconda.html
( pkg_development: line 93) ok https://docs.github.com/en/authentication/connecting-to-github-with-ssh
( pkg_development: line 20) ok https://img.shields.io/badge/code%20style-black-000000.svg
( index: line 36) ok https://img.shields.io/badge/license-Apache%202-cb2533.svg
( pkg_development: line 20) ok https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
( pkg_development: line 20) ok https://img.shields.io/badge/python-3.10-blue.svg
( pkg_development: line 20) ok https://img.shields.io/badge/version%20control-git-blue.svg?logo=github
( pkg_development: line 231) ok https://github.com/UBC-MOAD/MoaceanParcels/actions?query=workflow=sphinx-linkcheck
( pkg_development: line 20) ok https://github.com/UBC-MOAD/MoaceanParcels/issues
( pkg_development: line 20) ok https://moaceanparcels.readthedocs.io/en/latest/
( pkg_development: line 261) ok https://pytest-cov.readthedocs.io/en/latest/
( pkg_development: line 307) ok https://img.shields.io/github/issues/MIDOSS/WWatch3-Cmd?logo=github
( pkg_development: line 20) ok https://github.com/pre-commit/pre-commit
( pkg_development: line 20) ok https://readthedocs.org/projects/MoaceanParcels/badge/?version=latest
( pkg_development: line 20) ok https://github.com/UBC-MOAD/MoaceanParcels
( pkg_development: line 93) ok https://ubc-moad-docs.readthedocs.io/en/latest/ssh_access.html#copyyourpublicsshkeytogithub
( index: line 36) ok https://www.apache.org/licenses/LICENSE-2.0
( pkg_development: line 58) ok https://www.python.org/
( pkg_development: line 143) ok https://www.python.org/dev/peps/pep-0008/
( pkg_development: line 93) ok https://ubc-moad-docs.readthedocs.io/en/latest/ssh_access.html#secureremoteaccess
( pkg_development: line 177) ok https://www.sphinx-doc.org/en/master/
( pkg_development: line 177) ok https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
( pkg_development: line 20) ok https://img.shields.io/github/issues/UBC-MOAD/MoaceanParcels?logo=github
( pkg_development: line 171) ok https://readthedocs.org/projects/moaceanparcels/badge/?version=latest
build succeeded.
Look for any errors in the above output or in _build/linkcheck/output.txt
make linkcheck is run monthly via a scheduled GitHub Actions workflow
Running the Unit Tests
The test suite for the MoaceanParcels package is in MoaceanParcels/tests/
.
The pytest tool is used for test parametrization and as the test runner for the suite.
With your moacean-parcels development environment activated, use:
(moacean-parcels)$ cd MoaceanParcels/
(moacean-parcels)$ pytest
to run the test suite. The output looks something like:
**add example pytest output**
You can monitor what lines of code the test suite exercises using the coverage.py and pytest-cov tools with the command:
(moacean-parcels)$ cd MoaceanParcels/
(moacean-parcels)$ pytest --cov=./
and generate a test coverage report with:
(moacean-parcels)$ coverage report
to produce a plain text report, or
(moacean-parcels)$ coverage html
to produce an HTML report that you can view in your browser by opening
MoaceanParcels/htmlcov/index.html
.
Version Control Repository
The MoaceanParcels package code and documentation source files are available as a Git repository at https://github.com/UBC-MOAD/MoaceanParcels.
Issue Tracker
Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/UBC-MOAD/MoaceanParcels/issues.
License
The code and documentation of the MOAD OceanParcels kernels and utilities project are copyright 2021 – present by UBC EOAS MOAD Group and The University of British Columbia.
They are licensed under the Apache License, Version 2.0. https://www.apache.org/licenses/LICENSE-2.0 Please see the LICENSE file for details of the license.