contributing.rst

Contributing to These Docs

Additions, improvements, and corrections to these docs are always welcome.

The quickest way to fix typos, etc. on existing pages is to use the :guilabel:`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, the instructions below explain how to:

• clone the repository from GitHub
• set up a conda environment in which you can build the docs locally instead of having to push commits to GitHub to trigger a build on readthedocs.org
• build the docs with your changes, and preview them in Firefox

Getting the Repo

Clone the MIDOSS documentation repository from GitHub with:

$ git clone [email protected]:MIDOSS/docs.git

or copy the URI (the stuff after git clone above) from the :guilabel:`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 :ref:`SecureRemoteAccess` docs to set up your SSH keys and :ref:`CopyYourPublicSshKeyToGitHub`.

Docs Build Environment

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

$ cd docs
$ conda env create -f environment.yaml
$ conda activate midoss-docs

To deactivate the environment use:

(midoss-docs)$ conda deactivate

Note

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

$ source activate midoss-docs

and

(midoss-docs)$ source deactivate

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

Building and Previewing the Documentation

The MIDOSS documentation is written in reStructuredText and converted to HTML using Sphinx. Creating a :ref:`MIDOSS-DocsBuildEnvironment` as described above includes the installation of Sphinx. Building the documentation is driven by the :file:`docs/Makefile`. With your midoss-docs environment activated, use:

(midoss-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.5
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...
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 :file:`docs/_build/html/`. You can open the :file:`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:

(midoss-docs)$ firefox _build/html/index.html

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://midoss-docs.readthedocs.io/en/latest/.

Link Checking the Documentation

Use the commmand:

(midoss-docs)$ make linkcheck

to check the documentation for broken links. The output looks something like:

Running Sphinx v3.2.1
making output directory... done
loading intersphinx inventory from https://salishsea-nowcast.readthedocs.io/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [linkcheck]: targets for 9 source files that are out of date
updating environment: [new config] 9 added, 0 changed, 0 removed
reading sources... [100%] python_code/library_code
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 11%] CONTRIBUTORS
(line   20) ok        https://scarp.ubc.ca/people/stephanie-chang
(line   21) ok        https://www.dal.ca/faculty/agriculture/engineering/faculty-staff/our-faculty/haibo-niu.html
(line   19) ok        https://www.eoas.ubc.ca/~sallen/
writing output... [ 22%] TifFiles
(line   35) ok        https://www.earthdatascience.org/courses/earth-analytics-python/lidar-raster-data/open-lidar-raster-python/
writing output... [ 33%] contributing
(line   13) ok        https://creativecommons.org/licenses/by/4.0/
(line   13) ok        https://docs.python.org/3.8/
(line   13) ok        https://github.com/MIDOSS/docs/issues
(line   13) ok        https://midoss-docs.readthedocs.io/en/latest/
(line   13) ok        https://github.com/MIDOSS/docs/actions?query=workflow%3Asphinx-linkcheck
(line   38) ok        https://github.com/MIDOSS/docs
(line   13) ok        https://github.com/MIDOSS/docs
(line   44) ok        https://github.com/MIDOSS/docs
(line   78) ok        https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh
(line   58) ok        https://github.com/MIDOSS/docs
(line   46) ok        https://readthedocs.org/projects/midoss-docs/builds/
(line   93) ok        https://conda.io/en/latest/
(line  251) ok        https://git-scm.com/
(line   93) ok        https://docs.conda.io/en/latest/miniconda.html
(line  139) ok        https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
(line  139) ok        https://www.sphinx-doc.org/en/master/
(line  277) ok        https://github.com/MIDOSS/docs/blob/master/CONTRIBUTORS.rst
(line   13) ok        https://readthedocs.org/projects/midoss-docs/badge/?version=latest
(line   13) ok        https://img.shields.io/badge/python-3.6+-blue.svg
(line   13) ok        https://img.shields.io/badge/version%20control-git-blue.svg?logo=github
(line   13) ok        https://img.shields.io/badge/license-CC--BY-lightgrey.svg
(line   13) ok        https://github.com/MIDOSS/docs/workflows/sphinx-linkcheck/badge.svg
(line  193) ok        https://github.com/MIDOSS/docs/workflows/sphinx-linkcheck/badge.svg
(line   58) ok        https://img.shields.io/badge/version%20control-git-blue.svg?logo=github
(line   13) ok        https://img.shields.io/github/issues/MIDOSS/docs?logo=github
(line  259) ok        https://img.shields.io/github/issues/MIDOSS/docs?logo=github
writing output... [ 44%] index
writing output... [ 55%] models/index
writing output... [ 66%] models/mohid_on_graham
(line   15) ok        https://docs.computecanada.ca/wiki/Graham
(line   48) ok        https://docs.computecanada.ca/wiki/Storage_and_file_management
(line   87) -ignored- https://github.com/MIDOSS/MIDOSS-MOHID-CODE
(line   85) ok        https://github.com/MIDOSS/MOHID-Cmd
(line   91) -ignored- https://github.com/MIDOSS/MIDOSS-MOHID-CODE
(line   87) ok        https://github.com/MIDOSS/MOHID-Cmd
(line   93) -ignored- https://github.com/MIDOSS/MIDOSS-MOHID-grid
(line   85) ok        https://github.com/UBC-MOAD/moad_tools
(line  121) ok        https://packaging.python.org/tutorials/installing-packages/#installing-to-the-user-site
(line   89) ok        https://github.com/SalishSeaCast/NEMO-Cmd
(line   15) ok        http://www.mohid.com/
(line   95) ok        https://github.com/MIDOSS/MIDOSS-MOHID-config
(line   91) ok        http://www.mohid.com/
(line  197) ok        https://docs.computecanada.ca/wiki/Running_jobs#Interactive_jobs
(line  188) ok        http://wiki.mohid.com/index.php?title=Mohid_Framework
(line  188) ok        http://wiki.mohid.com/index.php?title=Mohid_Base_2
(line  188) ok        http://wiki.mohid.com/index.php?title=Mohid_Water
(line  188) ok        http://wiki.mohid.com/index.php?title=Mohid_Base_1
writing output... [ 77%] models/wwatch3_on_graham
(line  254) ok        https://salishsea-nowcast.readthedocs.io/en/latest/pkg_development.html#salishseanowcastdevelopmentenvironment
(line  245) ok        https://salishsea-nowcast.readthedocs.io/en/latest/workers.html#makeww3currentfile-worker
(line  258) ok        https://salishsea-nowcast.readthedocs.io/en/latest/workers.html#makeww3windfile-worker
(line   83) ok        https://github.com/SalishSeaCast/SalishSeaWaves
(line  245) ok        https://salishsea-nowcast.readthedocs.io/en/latest/workers.html#makeww3windfile-worker
(line   15) ok        https://polar.ncep.noaa.gov/waves/wavewatch/
writing output... [ 88%] python_code/index
writing output... [100%] python_code/library_code
(line   92) ok        https://salishsea-meopar-tools.readthedocs.io/en/latest/python_packaging/library_code.html#imports
(line   87) ok        https://salishsea-meopar-tools.readthedocs.io/en/latest/python_packaging/library_code.html
(line   20) ok        https://www.python.org/dev/peps/pep-0008/
(line   94) ok        https://salishsea-meopar-tools.readthedocs.io/en/latest/python_packaging/library_code.html#return-simplenamespace-from-functions
(line   93) ok        https://salishsea-meopar-tools.readthedocs.io/en/latest/python_packaging/library_code.html#public-and-private-objects

build succeeded.

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

:command:`make linkcheck` is run monthly via a scheduled GitHub Actions workflow

Version Control Repository

The MIDOSS documentation source files are available as a Git repository at https://github.com/MIDOSS/docs.

Issue Tracker

Documentation tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/MIDOSS/docs/issues.

License

The MEOPAR MIDOSS Project Documentation is copyright 2018 – present by the MIDOSS project contributors, The University of British Columbia, and Dalhousie University.

It is licensed under a Creative Commons Attribution 4.0 International License.