make_midoss_forcing Package Development¶
The Make-MIDOSS-Forcing package (make_midoss_forcing) is Make Salish Sea HDF5 Forcing Files for MIDOSS Runs
Python Versions¶
The make_midoss_forcing package is developed and tested using Python 3.9. It is intended to work in environments using Python>=3.8. The package uses some Python language features that are not available in versions prior to 3.6, in particular:
formatted string literals (aka f-strings)
Getting the Code¶
Clone the code and documentation repository from GitHub with:
$ git clone git@github.com:MIDOSS/Make-MIDOSS-Forcing.git
Development Environment¶
Setting up an isolated development environment using Conda is recommended. Assuming that you have Miniconda installed, you can create and activate an environment called make-midoss-forcing that will have all of the Python packages necessary for development, testing, and building the documentation with the commands below.
$ cd Make-MIDOSS-Forcing
$ conda env create -f envs/environment-dev.yaml
$ conda activate make-midoss-forcing
(make-midoss-forcing)$ python3 -m pip install --editable .
The --editable option in the pip install command above installs the 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:
(make-midoss-forcing)$ conda deactivate
Coding Style¶
The Make-MIDOSS-Forcing 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 Make-MIDOSS-Forcing
$ conda activate make_midoss_forcing
(make-midoss-forcing)$ black ./
in the repository root directory. The output looks something like:
reformatted /media/doug/warehouse/MIDOSS/Make-MIDOSS-Forcing/make_midoss_forcing/forcing_paths.py
All done! ✨ 🍰 ✨
1 file reformatted, 6 files left unchanged.
Building the Documentation¶
The documentation for the Make-MIDOSS-Forcing 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://make-midoss-forcing.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 make-midoss-forcing environment activated,
use:
(make-midoss-forcing)$ (cd docs && make clean html)
to do a clean build of the documentation. The output looks something like:
Running Sphinx v2.2.1
making output directory... done
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: [new config] 2 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... genindexdone
writing additional pages...
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 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 Bitbucket the documentation is automatically re-built and rendered at https://make-midoss-forcing.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 make-midoss-forcing) environment activated, use:
(make-midoss-forcing))$ cd Make-MIDOSS-Forcing)/docs/
(make-midoss-forcing)) docs$ make linkcheck
The output looks something like:
Running Sphinx v2.2.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
(line 37) ok https://img.shields.io/badge/license-Apache%202-cb2533.svg
(line 37) ok https://www.apache.org/licenses/LICENSE-2.0
(line 47) ok https://www.apache.org/licenses/LICENSE-2.0
writing output... [100%] pkg_development
(line 21) ok https://docs.python.org/3.8/
(line 55) ok https://www.python.org/
(line 59) ok https://docs.python.org/3/reference/lexical_analysis.html#f-strings
(line 61) ok https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep519
(line 21) ok https://black.readthedocs.io/en/stable/
(line 21) ok https://bitbucket.org/midoss/make-midoss-forcing/
(line 21) ok https://bitbucket.org/midoss/make-midoss-forcing/issues?status=new&status=open
(line 103) ok https://conda.io/en/latest/
(line 21) ok https://make-midoss-forcing.readthedocs.io/en/latest/
(line 71) ok https://bitbucket.org/midoss/make-midoss-forcing/
(line 138) ok https://www.python.org/dev/peps/pep-0008/
(line 164) ok https://make-midoss-forcing.readthedocs.io/en/latest/
(line 103) ok https://docs.conda.io/en/latest/miniconda.html
(line 77) ok https://bitbucket.org/midoss/make-midoss-forcing/
(line 211) ok https://make-midoss-forcing.readthedocs.io/en/latest/
(line 170) ok http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
(line 170) ok http://www.sphinx-doc.org/en/master/
(line 103) ok https://www.anaconda.com/distribution/
(line 241) ok https://docs.pytest.org/en/latest/
(line 21) ok https://img.shields.io/badge/python-3.6+-blue.svg
(line 21) ok https://img.shields.io/badge/version%20control-hg-blue.svg
(line 259) ok https://coverage.readthedocs.io/en/latest/
(line 21) ok https://img.shields.io/badge/code%20style-black-000000.svg
(line 21) ok https://readthedocs.org/projects/make-midoss-forcing/badge/?version=latest
(line 301) ok https://img.shields.io/bitbucket/issues/midoss/make-midoss-forcing.svg
(line 307) ok https://bitbucket.org/midoss/make-midoss-forcing/issues
(line 91) ok https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html
(line 293) ok https://www.mercurial-scm.org/
(line 21) ok https://img.shields.io/bitbucket/issues/midoss/make-midoss-forcing.svg
build finished.
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 Make-MIDOSS-Forcing package is in Make-MIDOSS-Forcing/tests/
.
The pytest tool is used for test parametrization and as the test runner for the suite.
With your make-midoss-forcing development environment activated, use:
(make-midoss-forcing)$ cd Make-MIDOSS-Forcing/
(make-midoss-forcing)$ py.test
to run the test suite. The output looks something like:
**add example pytest output**
You can monitor what lines of code the test suite exercises using the coverage.py and pytest-cov tools with the command:
(make-midoss-forcing)$ cd Make-MIDOSS-Forcing/
(make-midoss-forcing)$ pytest --cov=./
The test coverage report will be displayed below the test suite run output.
Alternatively, you can use
(make-midoss-forcing)$ pytest --cov=./ --cov-report html
to produce an HTML report that you can view in your browser by opening Make-MIDOSS-Forcing/htmlcov/index.html
.
Version Control Repository¶
The Make-MIDOSS-Forcing package code and documentation source files are available as a Git repository at https://github.com/MIDOSS/Make-MIDOSS-Forcing.
Issue Tracker¶
Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/MIDOSS/Make-MIDOSS-Forcing/issues.
License¶
The code and documentation of the Make MIDOSS Forcing project are copyright 2019-2021 the MIDOSS project contributors, The University of British Columbia, and Dalhousie University.
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.