GoMSS_Nowcast Package Development¶
Getting the Code¶
Clone the code and documentation repository from Bitbucket with:
$ hg clone ssh://hg@bitbucket.org/gomss-nowcast/gomss_nowcast GoMSS_Nowcast
or
$ hg clone https://your_userid@bitbucket.org/gomss-nowcast/gomss_nowcast GoMSS_Nowcast
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 gomss-nowcast that will have all of the Python packages necessary for development, testing, and building the documentation with the commands:
$ cd GoMSS_Nowcast
$ conda env create -f environment-dev.yaml
$ source activate gomss-nowcast
(gomss-nowcast)$ pip install --editable .
The --editable option in the pip install command above installs the GoMSS_Nowcast package from the cloned repo via symlinks so that the installed package will be automatically updated as the repo evolves.
To deactivate the environment use:
(gomss-nowcast)$ source deactivate
Coding Style¶
The GoMSS_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 GoMSS_Nowcast
$ conda activate gomss-nowcast
(gomss-nowcast)$ black ./
in the repository root directory. The output looks something like:
reformatted /media/doug/warehouse/43ravens/projects/gomss-nowcast/GoMSS_Nowcast/nowcast/next_workers.py
reformatted /media/doug/warehouse/43ravens/projects/gomss-nowcast/GoMSS_Nowcast/nowcast/figures/day_avg_tracer.py
reformatted /media/doug/warehouse/43ravens/projects/gomss-nowcast/GoMSS_Nowcast/tests/test_next_workers.py
reformatted /media/doug/warehouse/43ravens/projects/gomss-nowcast/GoMSS_Nowcast/nowcast/workers/run_nemo.py
reformatted /media/doug/warehouse/43ravens/projects/gomss-nowcast/GoMSS_Nowcast/tests/workers/test_run_nemo.py
All done! ✨ 🍰 ✨
5 files reformatted, 20 files left unchanged.
Building the Documentation¶
The documentation for the GoMSS_Nowcast 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 gomss-nowcast development environment activated,
use:
(gomss-nowcast)$ (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.4.1
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from https://nemo-nowcast.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://docs.python.org/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%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
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.
Build finished. 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 have write access to the repository on Bitbucket, whenever you push changes to Bitbucket the documentation is automatically re-built and rendered at https://gomss-nowcast-system.readthedocs.io/en/latest/.
Running the Unit Tests¶
The test suite for the GoMSS_Nowcast package is in GoMSS_Nowcast/tests/.
The pytest tool is used for test parametrization and as the test runner for the suite.
With your gomss-nowcast development environment activated, use:
(gomss-nowcast)$ cd GoMSS_Nowcast/
(gomss-nowcast)$ py.test
to run the test suite. The output looks something like:
============================ test session starts ============================
platform linux -- Python 3.5.1, pytest-2.9.2, py-1.4.31, pluggy-0.3.1
rootdir: /media/doug/warehouse/43ravens/projects/gomss-nowcast/NEMO_Nowcast, inifile:
collected 164 items
tests/test_next_workers.py ......
======================== 6 passed in 0.001 seconds =========================
You can monitor what lines of code the test suite exercises using the coverage.py tool with the command:
(gomss-nowcast)$ cd GoMSS_Nowcast/
(gomss-nowcast)$ coverage run -m py.test
and generate a test coverage report with:
(gomss-nowcast)$ coverage report
to produce a plain text report, or
(gomss-nowcast)$ coverage html
to produce an HTML report that you can view in your browser by opening GoMSS_Nowcast/htmlcov/index.html.
Version Control Repository¶
The GoMSS_Nowcast package code and documentation source files are available as a Mercurial repository at https://bitbucket.org/gomss-nowcast/gomss_nowcast.
Issue Tracker¶
Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://bitbucket.org/gomss-nowcast/gomss_nowcast/issues.
License¶
The GoMSS_Nowcast system code and documentation are copyright 2016-2019 by Doug Latornell, 43ravens.
They are licensed under the Apache License, Version 2.0. http://www.apache.org/licenses/LICENSE-2.0 Please see the LICENSE file for details of the license.