Adding subdirectories for versioned docs.

Fixes #472.

docs/conf.py

@@ -54,9 +54,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = get_distribution('gcloud').version
-# The full version, including alpha/beta/rc tags.
-release = get_distribution('gcloud').version
+release = os.getenv('SPHINX_RELEASE', get_distribution('gcloud').version)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

scripts/get_version.py

@@ -0,0 +1,2 @@
+from pkg_resources import get_distribution
+print get_distribution('gcloud').version

scripts/update_docs.sh

@@ -16,27 +16,59 @@
 
 set -ev
 
-# Build new docset in docs/_build from master.
-tox -e docs
+# Adding GitHub pages branch. `git submodule add` checks it
+# out at HEAD.
+GH_PAGES_DIR="ghpages"
 git submodule add -b gh-pages \
     "https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME}" \
-    ghpages
-cp -R docs/_build/html/* ghpages/
-cd ghpages
-# allow "git add" to fail if there aren't new files.
-set +e
+    ${GH_PAGES_DIR}
+
+# Determine if we are building a new tag or are building docs
+# for master. Then build new docset in docs/_build from master.
+if [[ -z "${TRAVIS_TAG}" ]]; then
+    SPHINX_RELEASE=$(git log -1 --pretty=%h) tox -e docs
+else
+    # Sphinx will use the package version by default.
+    tox -e docs
+fi
+
+# Get the current version. Assumes the PWD is the root of the git repo.
+# We run this after `tox -e docs` to make sure the `docs` env is
+# set up.
+CURRENT_VERSION=$(.tox/docs/bin/python scripts/get_version.py)
+
+# Update gh-pages with the created docs.
+cd ${GH_PAGES_DIR}
+if [[ -z "${TRAVIS_TAG}" ]]; then
+    git rm -fr master/
+    cp -R ../docs/_build/html/ master/
+else
+    if [[ -d ${CURRENT_VERSION} ]]; then
+        echo "The directory ${CURRENT_VERSION} already exists."
+        exit 1
+    fi
+    git rm -fr latest/
+    # Put the new release in latest and with the actual version.
+    cp -R ../docs/_build/html/ latest/
+    cp -R ../docs/_build/html/ "${CURRENT_VERSION}/"
+fi
+
+# Update the files push to gh-pages.
 git add .
-set -e
 git status
+
 # H/T: https://github.com/dhermes
-if [[ -n "$(git status --porcelain)" ]]; then
-    # Commit to gh-pages branch to apply changes.
-    git config --global user.email "[email protected]"
-    git config --global user.name "travis-ci"
-    git commit -m "Update docs after merge to master."
-    git push \
-        "https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME}" \
-        HEAD:gh-pages
-else
+if [[ -z "$(git status --porcelain)" ]]; then
     echo "Nothing to commit. Exiting without pushing changes."
+    exit
 fi
+
+# Commit to gh-pages branch to apply changes.
+git config --global user.email "[email protected]"
+git config --global user.name "travis-ci"
+git commit -m "Update docs after merge to master."
+# NOTE: This may fail if two docs updates (on merges to master)
+#       happen in close proximity.
+git push \
+    "https://${GH_OAUTH_TOKEN}@github.com/${GH_OWNER}/${GH_PROJECT_NAME}" \
+    HEAD:gh-pages