Documentation Maintenance¶

The GoMSS Nowcast project documentation can be edited on-line in the bitbucket.org interface by following the links in the upper right-hand corner of any page of the rendered pages.

This section described the set-up that you need to do if you want to edit the documentation on your own computer, and render it locally to HTML to preview your changes before you commit and push them to the public repository.

Software Versions¶

The GoMSS Nowcast project documentation is developed and maintained using Python 3.5 or later, and Sphinx 1.4.1 or later.

Getting the Source Files¶

Use Mercurial to clone the documentation repository from the gomss-nowcast team account on bitbucket.org with the command:

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

$ hg clone https://<your_userid>@bitbucket.org/gomss-nowcast/docs

if you don’t have ssh key authentication set up on Bitbucket.

Working Environment¶

Setting up an isolated development environment using Conda is recommended. Assuming that you have Miniconda3 or the Anaconda Python distribution installed, you can create and activate an environment called gomss-nowcast-docs that will have all of the Python packages necessary to build the documentation on your computer with the commands:

$ cd docs
$ conda create -n gomss-nowcast-docs python=3 sphinx
$ source activate gomss-nowcast-docs

You can edit the documentation files in any code-type editor. They are plain text files. The files are written in reStructuredText and converted to HTML using Sphinx.

To deactivate the environment use:

(gomss-nowcast-docs)$ source deactivate

Building the Documentation to Preview Changes¶

Building the documentation is driven by docs/Makefile. With your Working Environment activated, use:

(gomss-nowcast-docs)$ cd docs
(gomss-nowcast-docs)$ make clean html

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

rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.4.1
making output directory...
loading pickled environment... not yet created
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: 3 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.

Build finished. 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 in your browser to preview the results of the build before committing and pushing your changes to Bitbucket.

Whenever you push changes to the docs repository on Bitbucket the documentation is automatically re-built and rendered at http://gomss-nowcast.readthedocs.io/en/latest/.

Version Control Repository¶

The GoMSS Nowcast project documentation source files are available docs Mercurial repository at https://bitbucket.org/gomss-nowcast/docs.

Issue Tracker¶

Development tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://bitbucket.org/gomss-nowcast/docs/issues.