SalishSeaTools Package Development

Python Versions

The SalishSeaTools package is developed and tested using Python 3.5 or later. However, the package must also run under Python 2.7 for use on the Westgrid HPC platform.

Getting the Code

Clone the tools code and documentation repository from Bitbucket with:

$ hg clone ssh://hg@bitbucket.org/salishsea/tools

or

$ hg clone https://<your_userid>@bitbucket.org/salishsea/tools

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

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 salishsea-tools that will have all of the Python packages necessary for development, testing, and building the documentation with the commands:

$ cd tools
$ conda env create -f SalishSeaTools/environment.yaml
$ source activate salishsea-tools
(salishsea-tools)$ pip install --editable SalishSeaTools

The --editable option in the pip install commands above installs the SalishSeaTools and SalishSeaTools packaged from the tools via symlinks so that salishsea in the salishsea-tools environment will be automatically updated as the repo evolves.

To deactivate the environment use:

(salishsea-tools)$ source deactivate

Building the Documentation

The documentation for the SalishSeaTools package is written in reStructuredText and converted to HTML using Sphinx. Creating a Development Environment as described above includes the installation of Sphinx. The documentation is integrated into the tools docs. Building the documentation is driven by tools/docs/Makefile. With your salishsea-tools development environment activated, use:

(salishsea-tools)$ cd tools
(salishsea-tools)$ (cd docs && make clean html)

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

rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.3.1
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from http://salishsea-meopar-docs.readthedocs.org/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 40 source files that are out of date
updating environment: 40 added, 0 changed, 0 removed
reading sources... [100%] results_server/nowcast-green
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] results_server/nowcast-green
generating indices...
highlighting module code... [100%] salishsea_tools.hg_commands
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 tools/docs/_build/html/. You can open the SalishSeaTools/index.html file in that directory tree in your browser to preview the results of the build before committing and pushing your changes to Bitbucket.

Whenever you push changes to the tools on Bitbucket the documentation is automatically re-built and rendered at https://salishsea-meopar-tools.readthedocs.org/en/latest/SalishSeaTools/.

Running the Unit Tests

The test suite for the SalishSeaTools package is in tools/SalishSeaTools/tests/. The pytest tools is used for test fixtures and as the test runner for the suite.

With your salishsea-tools development environment activated, use:

(salishsea-tools)$ cd tools/SalishSeaTools/
(salishsea-tools)$ py.test

to run the test suite. The output looks something like:

============================ test session starts =============================
platform linux -- Python 3.5.1, pytest-2.8.5, py-1.4.31, pluggy-0.3.1
rootdir: /home/doug/Documents/MEOPAR/tools/SalishSeaTools, inifile:
collected 189 items

tests/test_bathy_tools.py ........
tests/test_hg_commands.py ...........
tests/test_namelist.py ..............
tests/test_nc_tools.py ...............................................
tests/test_stormtools.py ....
tests/test_teos_tools.py ............
tests/test_tidetools.py .
tests/test_unit_conversions.py .............................................
tests/test_viz_tools.py ...............................
tests/test_wind_tools.py ................

========================= 189 passed in 1.38 seconds =========================

You can monitor what lines of code the test suite exercises using the coverage.py tool with the command:

(salishsea-tools)$ cd tools/SalishSeaTools/
(salishsea-tools)$ coverage run -m py.test

and generate a test coverage report with:

(salishsea-tools)$ coverage report

to produce a plain text report, or

(salishsea-tools)$ coverage html

to produce an HTML report that you can view in your browser by opening tools/SalishSeaTools/htmlcov/index.html.

The run the test suite under Python 2.7, create a Python 2.7 Development Environment.

Version Control Repository

The SalishSeaTools package code and documentation source files are available as part of the tools Mercurial repository at https://bitbucket.org/salishsea/tools.

Issue Tracker

Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://bitbucket.org/salishsea/tools/issues using the component tag SalishSeaTools.