moad_tools Package Development¶
The UBC EOAS MOAD Group Tools package (moad_tools) is a collection of Python modules that facilitate code reuse for the UBC EOAS MOAD Group.
The moad_tools package is developed using Python 3.9. It is tested for Python versions >=3.8. 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 email@example.com:UBC-MOAD/moad_tools.git
Setting up an isolated development environment using Conda is recommended. Assuming that you have the Anaconda Python Distribution or Miniconda3 installed, you can create and activate an environment called moad-tools that will have all of the Python packages necessary for development, testing, and building the documentation with the commands below:
$ cd moad_tools $ conda env create -f envs/environment-dev.yaml $ conda activate moad-tools (moad-tools)$ python3 -m pip install --editable .
The --editable option in the pip install command above installs the moad_tools package via a symlink so that the installed package will be automatically updated as the repo evolves.
To deactivate the environment use:
(moad-tools)$ conda deactivate
black is installed as part of the Development Environment setup.
To run black on the entire code-base use:
$ cd moad_tools $ conda activate moad-tools (moad-tools)$ black ./
in the repository root directory. The output looks something like:
reformatted /media/doug/warehouse/MOAD/moad_tools/docs/conf.py reformatted /media/doug/warehouse/MOAD/moad_tools/moad_tools/observations.py All done! ✨ 🍰 ✨ 2 files reformatted, 5 files left unchanged.
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
With your moad-tools environment activated,
(moad-tools)$ cd moad_tools/docs/ (moad-tools) docs$ make clean html
to do a clean build of the documentation. The output looks something like:
Removing everything under '_build'... Running Sphinx v3.1.1 making output directory... done loading intersphinx inventory from https://mohid-cmd.readthedocs.io/en/latest/objects.inv... loading intersphinx inventory from https://numpy.org/doc/1.18/objects.inv... loading intersphinx inventory from https://pandas.pydata.org/docs/objects.inv... loading intersphinx inventory from https://docs.python.org/3/objects.inv... loading intersphinx inventory from https://rasterio.readthedocs.io/en/latest/objects.inv... loading intersphinx inventory from https://xarray.pydata.org/en/stable/objects.inv... building [mo]: targets for 0 po files that are out of date building [html]: targets for 3 source files that are out of date updating environment: [new config] 3 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 py-modindexdone highlighting module code... [100%] moad_tools.observations writing additional pages... searchdone 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
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:
(moad-tools) docs$ firefox _build/html/index.html
Running the Unit Tests¶
The test suite for the moad_tools package is in
The pytest tool is used for test parametrization and as the test runner for the suite.
With your moad-tools development environment activated, use:
(mohid-cmd)$ cd moad_tools/ (mohid-cmd)$ pytest
to run the test suite. The output looks something like:
============================ test session starts ============================ platform linux -- Python 3.8.3, pytest-5.4.3, py-1.9.0, pluggy-0.13.1 rootdir: /media/doug/warehouse/MOAD/moad_tools collected 11 items tests/test_observations.py .. [ 18%] tests/test_random_oil_spills.py ......... [100%] ============================ 11 passed in 1.98s =============================
(mohid-cmd)$ cd moad_tools/ (mohid-cmd)$ pytest --cov=./
The test coverage report will be displayed below the test suite run output.
Alternatively, you can use
(mohid-cmd)$ pytest --cov=./ --cov-report html
to produce an HTML report that you can view in your browser by opening
The moad_tools 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
Version Control Repository¶
Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/SalishSeaCast/SalishSeaNowcast/issues
The UBC EOAS MOAD Group moad_tools Python package code and documentation are copyright 2018-2021 by the UBC EOAS MOAD Group and The University of British Columbia.
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.