NEMO-Cmd Package Development

Licensed under the Apache License, Version 2.0 Python Version Git on GitHub The uncompromising Python code formatter Documentation Status Sphinx linkcheck GitHub Workflow Status Codecov Testing Coverage Report CodeQL analysis Issue Tracker

Python Versions

Python Version

The NEMO-Cmd package is developed using Python 3.10. It is strongly recommended that the package be used under Python>=3.8. The Continuous Integration workflow on GitHub ensures that the package is tested for all versions of Python>=3.6. However, the package must also run under Python 3.5 for use on the Westgrid orcinus HPC platform. Python 3.5 is not covered by Continuous Integration and support for it will be dropped as soon as we stop using orcinus. So, seriously, don’t use this package under Python 3.5!

Getting the Code

Git on GitHub

Clone the code and documentation repository from GitHub with:

$ git clone git@github.com:SalishSeaCast/NEMO-Cmd.git

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

$ cd NEMO-Cmd
$ conda env create -f envs/environment-dev.yaml
$ conda activate nemo-cmd
(nemo-cmd)$ pip install --editable .

The --editable option in the pip install commands above installs the NEMO-Cmd package from the repository clone via symlinks so that nemo command in the nemo-cmd environment will be automatically updated as the repo evolves.

To deactivate the environment use:

(nemo-cmd)$ conda deactivate

Coding Style

The uncompromising Python code formatter

The NEMO-Cmd 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-Cmd
$ conda activate nemo-cmd
(nemo-cmd)$ black ./

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

reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/nemo_cmd/fspath.py
reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/tests/test_api.py
reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/nemo_cmd/run.py
reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/tests/test_run.py
reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/nemo_cmd/prepare.py
reformatted /media/doug/warehouse/MEOPAR/NEMO-Cmd/tests/test_prepare.py
All done! ✨ 🍰 ✨
6 files reformatted, 14 files left unchanged.

Building the Documentation

Documentation Status

The documentation for the NEMO-Cmd package is written in reStructuredText and converted to HTML using Sphinx.

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://nemo-cmd.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 GitHub 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 mohid-cmd development environment activated, use:

(nemo-cmd)$ (cd docs && make clean html)

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

Removing everything under '_build'...
Running Sphinx v3.3.0
making output directory... done
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://salishseacmd.readthedocs.io/en/latest/objects.inv...
loading intersphinx inventory from https://salishsea-meopar-docs.readthedocs.io/en/latest/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%] subcommands
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] subcommands
generating indices... genindex done
highlighting module code... [100%] nemo_cmd.prepare
writing additional pages... search done
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 NEMO-Cmd/docs/_build/html/. You can open the index.html file in that directory tree in your browser to preview the results of the build before committing and pushing your changes to GitHub.

Whenever you push changes to the NEMO-Cmd repository on GitHub the documentation is automatically re-built and rendered at https://nemo-cmd.readthedocs.io/en/latest/.

Running the Unit Tests

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

With your nemo-cmd development environment activated, use:

(salishsea-cmd)$ cd NEMO-Cmd/
(salishsea-cmd)$ py.test

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

=========================== test session starts =============================
platform linux -- Python 3.6.1, pytest-3.0.5, py-1.4.32, pluggy-0.4.0
rootdir: /media/doug/warehouse/MEOPAR/NEMO-Cmd, inifile:
collected 166 items

tests/test_api.py ........
tests/test_combine.py ............
tests/test_deflate.py ...
tests/test_gather.py ...
tests/test_namelist.py .............
tests/test_prepare.py .....................................................................................
tests/test_run.py ..........................................

======================== 166 passed in 1.68 seconds ========================

You can monitor what lines of code the test suite exercises using the coverage.py and pytest-cov tools with the command:

(salishsea-cmd)$ cd NEMO-Cmd/
(salishsea-cmd)$ pytest --cov=./

The test coverage report will be displayed below the test suite run output.

Alternatively, you can use

(salishsea-cmd)$ pytest --cov=./ --cov-report html

to produce an HTML report that you can view in your browser by opening NEMO-Cmd/htmlcov/index.html.

Continuous Integration

GitHub Workflow Status Codecov Testing Coverage Report

The NEMO-Cmd package unit test suite is run and a coverage report is generated whenever changes are pushed to GitHub. The results are visible on the repo actions page, from the green checkmarks beside commits on the repo commits page, or from the green checkmark to the left of the “Latest commit” message on the repo code overview page . The testing coverage report is uploaded to codecov.io

The GitHub Actions workflow configuration that defines the continuous integration tasks is in the .github/workflows/pytest-coverage.yaml file.

Version Control Repository

Git on GitHub

The NEMO-Cmd package code and documentation source files are available from the Git repository at https://github.com/SalishSeaCast/NEMO-Cmd.

Issue Tracker

Issue Tracker

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

License

Licensed under the Apache License, Version 2.0

The NEMO command processor and documentation are copyright 2013 – present by the `SalishCast 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.