How to generate the air water vv website and push to github hosting

Overview

We're using github for hosting, which simply takes the gh-pages branch of this repository as the source for the website. We are using Sphinx to generate the site from the source. In order to regenerate the site and push changes to the gh-pages branch you need to do the following:

1. Create a new clone of the repository where you will checkout the gh-pages branch
2. Build the html source into that gh-pages branch; and,
3. Commit and push your changes to the gh-pages branch

It looks more complicated that it really is. The basic idea is that you have your working air-water-vv repository as well as a new clone of the repository checked out to gh-pages in air-water-vv/../air-water-vv-docs/html. The new docs directory is already configured to build into that relative path.

The following assumes you are starting from your working clone of air-water-vv:

cd ..
mkdir  air-water-vv-docs
cd air-water-vv-docs
git clone git@github.com:erdc-cm/air-water-vv.git html
cd html
git checkout gh-pages

Now you have the gh-pages branch ready to receive changes to the website. You won't have to do that again unless you erase air-water-vv-docs/html.

Now you just need to run Sphinx to generate the website:

cd ../../air-water-vv/doc
make html

To view the site locally before pushing it do:

cd ../../../air-water-vv-docs/html
google-chrome index.html 

Finally, to commit your changes do something like

git status
git add NEW_FILES
git commit -a
git push