Merge PR #472 'xylar/add_compass_docs' into develop

Add Travis CI and skeleton COMPASS docs #472

This merge adds support for [Travis CI](https://travis-ci.org/) to run
on MPAS-Model pull requests.  Travis currently runs two tests:
* `docs`: builds a skeleton of documentation using a
 [ReadTheDocs](https://readthedocs.org/) template, similar to what is
 used for
 [MPAS-Analysis](https://mpas-dev.github.io/MPAS-Analysis/stable/index.html),
 [MPAS-Tools](https://mpas-dev.github.io/MPAS-Tools/stable/index.html),
 [geometric_features](https://mpas-dev.github.io/geometric_features/stable/index.html)
 and [pyremap](https://mpas-dev.github.io/pyremap/stable/index.html).
 The documentation is currently almost entirely focused on COMPASS,
 because that is where the most pressing need for improved
 documentation seems to be.
* `compass`: creates conda environment with the latest version of the
 [compass](https://github.com/MPAS-Dev/MPAS-Tools/blob/master/compass/meta.yaml)
 metapackage, then tests to make sure the 4 basic COMPASS scripts exist
 and their help screens can be seen (requiring that all their
 dependencies are present in the conda environment.)

Stubs are in place for adding future CI for `ocean`, `atmosphere`,
`lancice` and `seaice` if anyone would care to do this.

Author: mark-petersen

.travis.yml

@@ -0,0 +1,54 @@
+# Based on https://github.com/NOAA-ORR-ERD/gridded/blob/master/.travis.yml
+language: minimal
+
+sudo: false
+
+notifications:
+  email: false
+
+# safelist
+branches:
+  only:
+  - master
+  - develop
+  - ocean/develop
+  - ocean/coastal
+  - landice/devleop
+
+jobs:
+  include:
+    - name: "docs"
+    - name: "compass"
+    # Add new jobs, along with the corresponding travis_ci/install_<name>.bash
+    # and travis_ci/test_<name>.bash
+    #- name: "atmosphere"
+    #- name: "landice"
+    #- name: "ocean"
+    #- name: "seaice"
+# The following is not needed now but could be added as the "safelist" and
+# job list evolves
+#  exclude:
+#    -
+#      name: "compass"
+#      if: branch == seaice/develop OR branch == e3sm/develop
+
+env:
+  global:
+    secure: "Ckovv5psUv9pdBVaNjsgrk0hXGJbNTi5dzLSWsNQA3Ub4hUXvzgBvX1TgS+CZvq3fkJnxV6SYZIlOkrCqqxdlUzFewDiuzzYxEZObFZ8FceWiYs4K3LMS30MPLzIYaV9ORqXJ0/P/ii62KhGIraX7ryzZ5+IG5uDOd7gumD6GiCPURFQIGpWS7MasKmEQRnokrGO3B2JjGEB0vMTdMZGbj8XY+X4Q0zcdQnjrLtG7PiuED95CrfEI7HfJ/ifPRgI4EMey6YI89DUF6hdQ1N1QxyAnxlKBDkqCvy6uowej7xPwMMZsyykr6EoAcwk9kYluVRogKe1iBMq1P4WCOOUj3c3Q9Dp885TiXlsW1aDKT2RSkx/SV5cE73vrpUhmm2Nf/wWAZktOYJSGlmRqSnjkQhDJqQSOaIQbwBfUtuGMt0Go0Q/3/qlMc7I9AjG5yBuYcY8WN98qKABP3IKjSsIFUPyo1kXCHt++oV7z1p9oBdGS54e+9rEYWixvAwvw0GvrNrbQdiq2sq8BheI4ppzeSGoneHguNDn5QyVeMu4WZ0gsCwuVW0lXiuUSlYHG5ZctX1cQySCyL3IOcpYa1a1/DKINpkwr/Z7T8oOM+UHnXDK96UJfbaG5n5+JZOfWJ6N/Em7weKuwnRiobGQfDqlyEtc1hgcLfvMnkpikENKhss="
+
+before_install:
+  - |
+    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
+    bash miniconda.sh -b -p $HOME/miniconda
+    source $HOME/miniconda/etc/profile.d/conda.sh
+    conda activate base
+    conda config --set always_yes yes --set changeps1 no --set show_channel_urls true
+    conda update conda
+    conda config --add channels conda-forge --force
+    conda config --set channel_priority strict
+
+install:
+  - ./travis_ci/install_${TRAVIS_JOB_NAME}.bash
+
+script:
+  - ./travis_ci/test_${TRAVIS_JOB_NAME}.bash

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = mpas_model
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/compass/clean_testcase.rst

@@ -0,0 +1,37 @@
+.. _compass_clean_testcase:
+
+clean\_testcase.py
+==================
+
+This script is used to clean one or more test cases that have already been
+setup.
+
+It will remove directories and driver scripts that were generated as part of
+setting up a test case.
+
+Command-line options::
+
+    $ ./clean_testcase.py -h
+    usage: clean_testcase.py [-h] [-o CORE] [-c CONFIG] [-r RES] [-t TEST]
+                             [-n NUM] [-q] [-a] [--work_dir PATH]
+
+    This script is used to clean one or more test cases that have already been
+    setup.
+
+    It will remove directories / driver scripts that were generated as part of
+    setting up a test case.
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -o CORE, --core CORE  Core that contains configurations to clean
+      -c CONFIG, --configuration CONFIG
+                            Configuration to clean
+      -r RES, --resolution RES
+                            Resolution of configuration to clean
+      -t TEST, --test TEST  Test name within a resolution to clean
+      -n NUM, --case_number NUM
+                            Case number to clean, as listed from list_testcases.py. Can be a comma delimited list of case numbers.
+      -q, --quiet           If set, script will not write a command_history file
+      -a, --all             Is set, the script will clean all test cases in the work_dir.
+      --work_dir PATH       If set, script will clean case directories in work_dir rather than the current directory.
+