`AtlantisCmd` Package Development

The AtlantisCmd package (atlantis_cmd) is a command-line tool for doing various operations associated with the Salish Sea Atlantis project version of the CSIRO Atlantis ecosystem model. AtlantisCmd is based on, and provides Atlantis-specific extensions for https://github.com/SalishSeaCast/NEMO-Cmd.

Python Versions

The atlantis_cmd package is developed and tested using Python 3.10. The package uses some Python language features that are not available in versions prior to 3.8, in particular:

formatted string literals (aka f-strings) with = specifiers

Getting the Code

Clone the code and documentation repository from GitHub with:

$ git clone git@github.com:SS-Atlantis/AtlantisCmd.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

The AtlantisCmd package depends on the NEMO-Cmd package, so you need to clone its repo, NEMO-Cmd, beside your clone of AtlantisCmd repository.

Setting up an isolated development environment using Conda is recommended. Assuming that you have Miniconda3 installed, you can create and activate an environment called atlantis-cmd that will have all of the Python packages necessary for development, testing, and building the documentation with the commands below.

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

The --editable option in the pip install commands above install the packages from the cloned repos via symlinks so that the installed packages will be automatically updated as their repos evolves.

To deactivate the environment use:

(atlantis-cmd)$ conda deactivate

Coding Style

The AtlantisCmd 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 AtlantisCmd
$ conda activate atlantis_cmd
(atlantis-cmd)$ black ./

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

**add example black output**

Building the Documentation

The documentation for the AtlantisCmd 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 salishsea-nowcast development environment activated, use:

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

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

Running Sphinx v4.1.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 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... [ 50%] index
writing output... [100%] pkg_development
generating indices... genindex done
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 docs/_build.

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 GitHub, whenever you push changes to GitHub the documentation is automatically re-built and rendered at https://atlantiscmd.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 atlantis-cmd) environment activated, use:

(atlantis-cmd))$ cd AtlantisCmd/docs/
(atlantis-cmd)) docs$ make linkcheck

The output looks something like:

Running Sphinx v4.1.1
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... [ 50%] index
writing output... [100%] pkg_development


( pkg_development: line  255) ok        https://coverage.readthedocs.io/en/latest/
( pkg_development: line   20) ok        https://black.readthedocs.io/en/stable/
( pkg_development: line  237) ok        https://docs.pytest.org/en/latest/
( pkg_development: line   20) ok        https://docs.python.org/3.10/
( pkg_development: line  101) ok        https://conda.io/en/latest/
( pkg_development: line  101) ok        https://docs.conda.io/en/latest/miniconda.html
( pkg_development: line  289) ok        https://git-scm.com/
( pkg_development: line   58) ok        https://docs.python.org/3/reference/lexical_analysis.html#f-strings
( pkg_development: line   89) ok        https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh
( pkg_development: line   20) ok        https://atlantiscmd.readthedocs.io/en/latest/
( 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/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   20) ok        https://github.com/SS-Atlantis/AtlantisCmd/issues
( pkg_development: line   20) ok        https://github.com/SS-Atlantis/AtlantisCmd
( pkg_development: line   42) ok        https://github.com/SalishSeaCast/NEMO-Cmd
( pkg_development: line   20) ok        https://img.shields.io/github/issues/SS-Atlantis/AtlantisCmd?logo=github
( pkg_development: line   89) ok        https://ubc-moad-docs.readthedocs.io/en/latest/ssh_access.html#secureremoteaccess
( pkg_development: line   54) ok        https://www.python.org/
( pkg_development: line   89) ok        https://ubc-moad-docs.readthedocs.io/en/latest/ssh_access.html#copyyourpublicsshkeytogithub
( pkg_development: line  135) ok        https://www.python.org/dev/peps/pep-0008/
( pkg_development: line  165) ok        https://www.sphinx-doc.org/en/master/
( pkg_development: line  165) ok        https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
( pkg_development: line   20) ok        https://readthedocs.org/projects/AtlantisCmd/badge/?version=latest
( pkg_development: line  159) ok        https://readthedocs.org/projects/atlantiscmd/badge/?version=latest
(           index: line   36) ok        https://www.apache.org/licenses/LICENSE-2.0
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 AtlantisCmd package is in AtlantisCmd/tests/. The pytest tool is used for test parametrization and as the test runner for the suite.

With your atlantis-cmd development environment activated, use:

(atlantis-cmd)$ cd AtlantisCmd/
(atlantis-cmd)$ pytest

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

================================ test session starts =================================
platform linux -- Python 3.9.6, pytest-6.2.4, py-1.10.0, pluggy-0.13.1
Using --randomly-seed=3861485000
rootdir: /media/doug/warehouse/Atlantis/AtlantisCmd
plugins: randomly-3.8.0, cov-2.12.1
collected 1 item

tests/test_run.py .                                                                                                                                                                                                                                                                                            [100%]

================================= 1 passed in 0.17s ==================================

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

(atlantis-cmd)$ cd AtlantisCmd/
(atlantis-cmd)$ pytest --cov=./

and generate a test coverage report with:

(atlantis-cmd)$ coverage report

to produce a plain text report, or

(atlantis-cmd)$ coverage html

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

Continuous Integration

The AtlantisCmd 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

The AtlantisCmd package code and documentation source files are available as a Git repository at https://github.com/SS-Atlantis/AtlantisCmd.

Issue Tracker

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

License

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.

AtlantisCmd Package Development