`rpn-to-gemlam` Package Development

rpn-to-gemlam is a tool for generating atmospheric forcing files for the SalishSeaCast NEMO model from the ECCC 2007-2014 archival GEMLAM files produced by the experimental phase of the HRPDS model.

Python Versions

The rpn-to-gemlam package is developed and tested using Python 3.7. The package uses some Python language features that are not available in versions prior to 3.6, in particular:

formatted string literals (aka f-strings)
the file system path protocol

Getting the Code

Clone the code and documentation repository, and the tools repository from Bitbucket with:

$ git clone git@github.com:SalishSeaCast/rpn-to-gemlam.git
$ git clone git@github.com:SalishSeaCast/tools.git

or

$ git clone https://github.com/SalishSeaCast/rpn-to-gemlam.git
$ git clone https://github.com/SalishSeaCast/tools.git

if you don’t have ssh key authentication set up on GitHub.

Development Environment

Setting up an isolated development environment using Conda is recommended. Assuming that you have Anaconda Python Distribution or Miniconda3 installed, you can create and activate an environment called rpn-to-gemlam that will have all of the Python packages necessary for development, testing, and building the documentation with the commands:

$ cd rpn-to-gemlam
$ conda env create -f env/environment-dev.yaml
$ conda activate rpn-to-gemlam
(rpn-to-gemlam)$ python3 -m  pip install --editable ../tools/SalishSeaTools
(rpn-to-gemlam)$ python3 -m  pip install --editable .

The --editable option in the pip install command above installs the rpn_to_gemlam package from the cloned repo via symlinks so that the installed rpn_to_gemlam package will be automatically updated as the repo evolves.

To deactivate the environment use:

(rpn-to-gemlam)$ conda deactivate

Coding Style

The NEMO_Nowcast package uses the black code formatting tool to maintain a coding style that is very close to PEP 8.

black is installed as part of the Development Environment setup.

To run black on the entire code-base use:

$ cd NEMO_Nowcast
$ conda activate nemo-nowcast
(nemo-nowcast)$ black ./

in the repository root directory. The output looks something like:

reformatted /media/doug/warehouse/MEOPAR/rpn-to-gemlam/docs/conf.py
All done! ✨ 🍰 ✨
1 file reformatted, 3 files left unchanged.

Documentation

The :rpn-to-gemlam documentation is written in reStructuredText and converted to HTML using Sphinx.

If you have write access to the repository on Bitbucket, whenever you push changes to Bitbucket the documentation is automatically re-built and rendered at https://rpn-to-gemlam.readthedocs.io/en/latest/.

Additions, improvements, and corrections to these docs are always welcome.

The quickest way to fix typos, etc. on existing pages is to use the Edit on GitHub link in the upper right corner of the page to get to the online editor for the page on GitHub.

For more substantial work, and to add new pages, follow the instructions in the Development Environment section above. In the development environment you can build the docs locally instead of having to push commits to Bitbucket to trigger a build on readthedocs.org and wait for it to complete. Below are instructions that explain how to:

build the docs with your changes, and preview them in Firefox
check the docs for broken links

Building and Previewing the Documentation

Building the documentation is driven by the docs/Makefile. With your rpn-to-gemlam environment activated, use:

(rpn-to-gemlam)$ cd rpn-to-gemlam/docs/
(rpn-to-gemlam) docs$ make clean html

to do a clean build of the documentation. The output looks something like:

Removing everything under '_build'...
Running Sphinx v1.8.5
making output directory...
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 2 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
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

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. To preview in Firefox from the command-line you can do:

(rpn-to-gemlam) docs$ firefox _build/html/index.html

If you have write access to the repository on Bitbucket, whenever you push changes to Bitbucket the documentation is automatically re-built and rendered at https://rpn-to-gemlam.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 rpn-to-gemlam environment activated, use:

(rpn-to-gemlam)$ cd rpn-to-gemlam/docs/
(rpn-to-gemlam) docs$ make linkcheck

The output looks something like:

Running Sphinx v1.8.5
making output directory...
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, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [ 50%] index
(line   43) ok        https://www.apache.org/licenses/LICENSE-2.0
writing output... [100%] pkg_development
(line   21) ok        https://docs.python.org/3.7/
(line   56) ok        https://www.python.org/
(line   60) ok        https://docs.python.org/3/reference/lexical_analysis.html#f-strings
(line   62) ok        https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep519
(line   21) ok        https://black.readthedocs.io/en/stable/
(line   21) ok        https://rpn-to-gemlam.readthedocs.io/en/latest/
(line   92) ok        https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html
(line   21) ok        https://bitbucket.org/salishsea/rpn-to-gemlam/issues?status=new&status=open
(line  102) ok        https://www.anaconda.com/distribution/
(line   21) ok        https://bitbucket.org/salishsea/rpn-to-gemlam/
(line  137) ok        https://www.python.org/dev/peps/pep-0008/
(line  102) ok        https://conda.io/en/latest/
(line  102) ok        https://conda.io/en/latest/miniconda.html
(line  169) ok        http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
(line  169) ok        http://www.sphinx-doc.org/en/master/
(line   72) ok        https://bitbucket.org/salishsea/rpn-to-gemlam/
(line   78) ok        https://bitbucket.org/salishsea/rpn-to-gemlam
(line  174) ok        https://bitbucket.org/salishsea/rpn-to-gemlam
(line  185) ok        https://readthedocs.org/projects/rpn-to-gemlam/builds/
(line  246) ok        https://bitbucket.org/salishsea/rpn-to-gemlam

build succeeded.

Look for any errors in the above output or in _build/linkcheck/output.txt

Version Control Repository

The rpn-to-gemlam code and documentation source files are available in the rpn-to-gemlam Git repository at https://github.com/SalishSeaCast/rpn-to-gemlam.

Issue Tracker

Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/SalishSeaCast/rpn-to-gemlam/issues.

License

The code and documentation of the rpn-to-gemlam tool for generating SalishSeaCast NEMO atmospheric forcing files from ECCC RPN files are copyright 2019-2020 by the Salish Sea MEOPAR Project Contributors 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.

rpn-to-gemlam Package Development