gomss-site Web App Development¶

Python Versions¶

The gomss-site package is developed, tested, and deployed using Python 3.6 or later. 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)
the file system path protocol

Getting the Repo¶

Clone the gomss-site code and documentation repository from Bitbucket with:

$ hg clone ssh://hg@bitbucket.org/gomss-nowcast/gomss-site

$ hg clone https://<your-userid>@bitbucket.org/gomss-nowcast/gomss-site

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 the Anaconda Python Distribution or Miniconda3 installed, you can create and activate an environment called gomss-site that will have all of the Python packages necessary for development and testing of the app with the commands below:

$ cd gomss-site
$ conda env create -f environment-dev.yaml
$ source activate gomss-site
(gomss-site)$ pip install --editable .

The --editable option in the pip install command above installs the gomss-site package via a symlink so that the installed package will be automatically updated as the repo evolves.

To deactivate the environment use:

(gomss-site)$ source deactivate

Coding Style¶

The gomss-site 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:

$ black ./

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

gomss-site/gomss_site/views/nowcast_logs.py wasn't modified on disk since last run.
gomss-site/gomss_site/views/__init__.py wasn't modified on disk since last run.
gomss-site/__pkg_metadata__.py wasn't modified on disk since last run.
gomss-site/gomss_site/__init__.py wasn't modified on disk since last run.
gomss-site/__pkg_metadata__.py wasn't modified on disk since last run.
gomss-site/docs/conf.py wasn't modified on disk since last run.
gomss-site/tests/test_init.py wasn't modified on disk since last run.
gomss-site/tests/views/test_nowcast_logs.py wasn't modified on disk since last run.
gomss-site/setup.py wasn't modified on disk since last run.
reformatted gomss-site/gomss_site/views/landing.py
All done! ✨ 🍰 ✨
1 file reformatted, 11 files left unchanged.

Documentation¶

The :gomss-site documentation is written in reStructuredText and converted to HTML using Sphinx.

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-site.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 Bitbucket link in the upper right corner of the page to get to the online editor for the page on Bitbucket.

For more substantial work, and to add new pages, follow the instructions in the Getting the Repo section above, and then those below that explain how to:

set up a conda environment in which you can build the docs locally instead of having to push commits to Bitbucket to trigger a build on readthedocs.org and wait for it to complete
build the docs with your changes, and preview them in Firefox

Docs Build Environment¶

Setting up an isolated docs build environment using Conda is recommended. Assuming that you have the Anaconda Python Distribution or Miniconda3 installed, you can create and activate an environment called gomss-site-rtd that will have all of the Python packages necessary for building the documentation with the commands:

$ cd gomss-site
$ conda env create -f environment-rtd.yaml
$ conda activate gomss-site-rtd
(gomss-site-rtd)$ conda install -c defaults mock pillow sphinx sphinx_rtd_theme

The gomss-site-rtd environment should be almost identical to the environment that will be used to build the docs on readthedocs.org. That helps to resolve package dependency issues, etc. before docs changes are committed and pushed.

To deactivate the gomss-site-rtd environment use:

(gomss-site-rtd)$ conda deactivate

Note

If you are using a version of conda older than 4.4.0, the commands to activate and deactivate the environment are:

$ source activate gomss-site-rtd

and

(gomss-site-rtd)$ source deactivate

You can check what version of conda you are using with conda --version.

Building and Previewing the Documentation¶

Building the documentation is driven by the docs/Makefile. With your gomss-site-rtd environment activated, use:

(gomss-site-rtd)$ cd gomss-site/docs/
(gomss-site-rtd) docs$ make clean html

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

Removing everything under '_build'...
Running Sphinx v1.7.4
making output directory...
loading pickled environment... not yet created
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/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.

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. To preview in Firefox from the command-line you can do:

(gomss-site-rtd) docs$ firefox _build/html/index.html

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 gomss-site-rtd environment activated, use:

(gomss-site-rtd)$ cd gomss-site/docs/
(gomss-site-rtd) docs$ make linkcheck

The output looks something like:

(gomss-site-rtd) docs$ make linkcheck
Running Sphinx v1.7.4
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%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 50%] development
(line   20) ok        http://gomss-site.readthedocs.io/en/latest/?badge=latest
(line   20) ok        https://black.readthedocs.io/en/stable/
(line   20) ok        https://www.apache.org/licenses/LICENSE-2.0
(line   45) ok        https://docs.python.org/3.6/
(line   20) ok        https://docs.python.org/3.6/
(line   51) ok        https://www.python.org/
(line   57) ok        https://docs.python.org/3/reference/lexical_analysis.html#f-strings
(line   59) ok        https://docs.python.org/3/whatsnew/3.6.html#whatsnew36-pep519
(line   20) ok        https://bitbucket.org/gomss-nowcast/gomss-site/issues?status=new&status=open
(line   20) ok        https://bitbucket.org/gomss-nowcast/gomss-site/
(line   89) ok        https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html
(line  103) ok        http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
(line   69) ok        https://bitbucket.org/gomss-nowcast/gomss-site/
(line  103) ok        http://www.sphinx-doc.org/en/master/
(line   75) ok        https://bitbucket.org/gomss-nowcast/gomss-site/
(line  136) ok        https://conda.io/docs/
(line  136) ok        https://www.anaconda.com/download/
(line  136) ok        https://conda.io/docs/install/quick.html
(line  108) ok        https://gomss-site.readthedocs.io/en/latest/
(line  243) ok        https://www.mercurial-scm.org/
(line  269) ok        http://43ravens.ca/
(line  122) ok        https://readthedocs.org/projects/gomss-site/builds/
(line  230) ok        https://gomss-site.readthedocs.io/en/latest/
(line  257) ok        https://bitbucket.org/gomss-nowcast/gomss-site/issues
(line  151) ok        https://readthedocs.org/projects/gomss-site/builds/
(line  269) ok        https://bitbucket.org/gomss-nowcast/docs/src/default/CONTRIBUTORS.rst
writing output... [100%] index
(line   29) ok        https://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/index.html
(line   29) ok        https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/firstapp.html#firstapp-chapter
(line   22) ok        https://docs.pylonsproject.org/projects/pyramid/en/latest/index.html
(line   32) ok        https://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/index.html
(line   32) ok        https://docs.pylonsproject.org/projects/pyramid/en/latest/index.html#narrative-documentation

build succeeded.

Look for any errors in the above output or in _build/linkcheck/output.txt

Running the Unit Tests¶

The test suite for the gomss-site package is in gomss-site/tests/. The pytest tool is used for test parametrization and as the test runner for the suite.

With your gomss-site development environment activated, use:

(gomss-site)$ cd gomss-site/
(gomss-site)$ pytest

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

============================ test session starts ============================
platform linux -- Python 3.6.5, pytest-3.6.3, py-1.5.4, pluggy-0.6.0
rootdir: /media/doug/warehouse/43ravens/projects/gomss-nowcast/gomss-site, inifile:
collected 26 items

tests/test_init.py ..............                                      [ 53%]
tests/test_mako_filters.py .                                           [ 57%]
tests/views/test_figures.py ....                                       [ 73%]
tests/views/test_landing.py .                                          [ 76%]
tests/views/test_nowcast_logs.py ...                                   [ 88%]
tests/views/test_results_figures.py ...                                [100%]

========================= 26 passed in 1.56 seconds =========================

You can monitor what lines of code the test suite exercises using the coverage.py tool with the command:

(gomss-site)$ cd gomss-site/
(gomss-site)$ coverage run -m py.test

and generate a test coverage report with:

(gomss-site)$ coverage report

to produce a plain text report. The output looks something like:

---------------------------------------------------------------------------------
__pkg_metadata__.py                       5      5      0      0     0%   14-19
gomss_site/__init__.py                   27      1      0      0    96%   59
gomss_site/mako_filters.py                3      0      0      0   100%
gomss_site/views/__init__.py              0      0      0      0   100%
gomss_site/views/figures.py              17      1      2      0    95%   47
gomss_site/views/landing.py               5      0      0      0   100%
gomss_site/views/nowcast_logs.py         18      0      0      0   100%
gomss_site/views/results_figures.py      19      1      4      0    87%   65
tests/conftest.py                         7      0      0      0   100%
tests/test_init.py                       66      0     12      0   100%
tests/test_mako_filters.py                5      0      0      0   100%
tests/views/test_figures.py              23      0      0      0   100%
tests/views/test_landing.py              10      0      2      0   100%
tests/views/test_nowcast_logs.py         31      0      2      0   100%
tests/views/test_results_figures.py      22      0      2      0   100%
---------------------------------------------------------------------------------
TOTAL                                   258      8     24      0    96%

Alternatively, you can produce an HTML report that you can view in your browser with:

(gomss-site)$ coverage html

and view it by opening gomss-site/htmlcov/index.html.

Version Control Repository¶

The gomss-site package code and documentation source files are available in the gomss-site Mercurial repository at https://bitbucket.org/gomss-nowcast/gomss-site/.

Issue Tracker¶

Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://bitbucket.org/gomss-nowcast/gomss-site/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.