Add Travis CI and skeleton COMPASS docs

[xylar]

This merge adds support for Travis CI to run on MPAS-Model pull requests. Travis currently runs two tests:

• docs: builds a skeleton of documentation using a ReadTheDocs template, similar to what is used for MPAS-Analysis, MPAS-Tools, geometric_features and pyremap. 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 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.

[xylar]

@mark-petersen, @matthewhoffman, @mgduda, @akturner and @pwolfram, I want to make sure you are all okay with these changes, as they will propagate to other branches as develop gets merged to them. Please let me know if you have concerns.

[xylar]

@mark-petersen, @matthewhoffman, @mgduda, @akturner and @pwolfram, first, I would like permission to create a gh-pages branch:

Thegh-pages branch would be an essentially empty branch for the documentation to get merged to. This will appear at http://mpas-dev.github.io/MPAS-Model by default, thought we could put it somewhere else if that is not the desired location. It will create folders under that URL corresponding to each of the supported branches(stable for master; latest for develop; latest_ocean , latest_coastal and latest_landice for for ocean/develop, ocean/coastal and landice/develop, respectively) and for each future release tag (7.1, etc.), where the latest associated documentation will be available.

[xylar]

To add more CI in the future, uncomment one of these or add a new one, then add travis_ci/install_ocean.bash, travis_ci/test_ocean.bash, etc. to set up and run whatever tests are desired. It may be possible to set, compile and run MPAS itself in Travis if we don't make the tests too big.

[xylar]

This lets Travis log in as me to upload the documentation to the gh-pages branch (once we create it). This capability means that we need to be careful not to merge malicious code (e.g. "bug fixes" from an unknown contributor) that could use this ability to mess up the repo. Just want to make that risk known so we're vigilant, though I think it is very unlikely.

[xylar]

Obviously, just a placeholder for now.

[xylar]

Another placeholder

[xylar]

And another

[xylar]

@mgduda, do you have an answer to my question above about where the "official" MPAS version number can be found and parsed?

[xylar]

@mark-petersen, @matthewhoffman, @mgduda, @akturner and @pwolfram, first, I would like permission to create a gh-pages branch

Most of us were on the telecon discussing this on Monday and seemed okay with this plan as long as you aren't affected. Are you okay with me making an empty branch gh-pages where documentation will start appearing under http://mpas-dev.github.io/MPAS-Model? For example, http://mpas-dev.github.io/MPAS-Model/latest would be the first, and would point to the stub documentation generated once this PR is merged to develop.

For now, there would be no links to this documentation anywhere, since it's just a stub. But I would eventually add more prominent links once there is meaningful content.

[mark-petersen]

@xylar, thanks for being proactive with these modern tools. Automated PR testing and readTheDocs documentation has big advantages, so having this framework in place is very helpful.

This is a new capability that each core may take part in as they choose, so there is no downside here.

[mark-petersen]

@mgduda @matthewhoffman @akturner @pwolfram
If you could review this pull request this week, that would be helpful.

[xylar]

@mark-petersen, this should not be merged until the gh-pages branch has been created. I put back the "in progress" tag.

[matthewhoffman]

@xylar , is making the gh_pages tag something I can do? Also, did you resolve your question about an "official" MPAS version number? Would git describe serve that purpose?

[xylar]

gh-pages would be a nearly empty branch, rather than a tag.

Yes, I resolved the version number question. Thanks!

[xylar]

@matthewhoffman, here is the gist of what needs to happen (see https://gist.github.com/ramnathv/2227408):

cd /path/to/repo-name
git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx
echo "My GitHub Page" > index.html
git add .
git commit -a -m "First pages commit"
git push origin gh-pages

In other words, I need to create an empty (orphaned) branch that Travis CI will then populate with various versions of the documentation.

I am happy to to this (and I believe I have the necessary permission) but I just want to make sure no one will be unhappy about it.

[xylar]

Okay, I have created the gh-pages branch. On the recent MPAS-Developers telecons I got the sense that @mgduda and @akturner are okay with this as long as it doesn't affect the seaice/develop branch. So I'm going to remove you as reviewers.

@mark-petersen, @matthewhoffman, and @pwolfram, could you take a look again and make sure you don't have objections. I realize it will be easier to tell once these changes propagate to ocean/develop, landice/develop and ocean/coastal, so for now I'm mainly wanting to make sure there aren't any major red flags.

[pwolfram]

@xylar, took a really quick look. I'd recommend we get this published and revisit as we go. Having something, which we don't have, is much better for this than nothing and I appreciate you kicking this off so we have something to build on that can be used to increase clarity.

[mark-petersen]

@matthewhoffman any comments, or can we merge?

[xylar]

Thanks for the reviews!

[xylar]

Thanks, @mark-petersen for merging this and everyone else for your reviews.

[xylar]

@mark-petersen, it there a good time for merging develop to ocean/develop to bring in these changes? It's not a big rush but I do plan to work on documentation as I have time once this goes in.

[mark-petersen]

I was hoping to get in 562 and 449 into develop, and then merge in develop. But hopefully in the next week.