Merge pull request #433 from MDAnalysis/issue/386

automatic doc deployment (closes #386)

.travis.yml

@@ -27,11 +27,26 @@ install:
 # command to run tests
 script:
   - ./testsuite/MDAnalysisTests/mda_nosetests -v --with-coverage --cover-package MDAnalysis --processes=2 --process-timeout=120 --with-memleak
-  - test $TRAVIS_PULL_REQUEST == "false" && test $TRAVIS_BRANCH == "develop" && cd ./package && python setup.py build_ext --inplace && cd ./doc/sphinx && make clean html || true
+  - |
+     test ${TRAVIS_PULL_REQUEST} == "false" && \
+     test ${TRAVIS_BRANCH} == ${GH_DOC_BRANCH} && \
+     test "${TRAVIS_BUILD_NUMBER}.1" == "${TRAVIS_JOB_NUMBER}" && \
+     (cd ./package && python setup.py build_ext --inplace) && \
+     (cd ./package/doc/sphinx && make clean html) || \
+     true
 after_success:
   - coveralls
-  - test $TRAVIS_PULL_REQUEST == "false" && test $TRAVIS_BRANCH == "develop" && bash ./maintainer/deploy_docs.sh
+  - |
+     test ${TRAVIS_PULL_REQUEST} == "false" && \
+     test ${TRAVIS_BRANCH} == ${GH_DOC_BRANCH} && \
+     test "${TRAVIS_BUILD_NUMBER}.1" == "${TRAVIS_JOB_NUMBER}" && \
+     bash ./maintainer/deploy_docs.sh
   
 env:
    global:
-      secure: "HIj3p+p2PV8DBVg/KGUx6n83KwB0ASE5FwOn0SMB9zxnzAqe8sapwdBQdMdq0sXB7xT1spJqRxuxOMVEVn35BNLu7bxMLfa4287C8YXcomnvmv9xruxAsjsIewnNQ80vtPVbQddBPxa4jKbqgPby5QhhAP8KANAqYe44pIV70fY="
+      - secure: "HIj3p+p2PV8DBVg/KGUx6n83KwB0ASE5FwOn0SMB9zxnzAqe8sapwdBQdMdq0sXB7xT1spJqRxuxOMVEVn35BNLu7bxMLfa4287C8YXcomnvmv9xruxAsjsIewnNQ80vtPVbQddBPxa4jKbqgPby5QhhAP8KANAqYe44pIV70fY="
+      - GH_DOC_BRANCH: develop
+      - GH_REPOSITORY: github.com/MDAnalysis/mdanalysis.git
+      - GIT_CI_USER: TravisCI
+      - GIT_CI_EMAIL: [email protected]
+      - MDA_DOCDIR: package/doc/html

maintainer/deploy_docs.sh

@@ -7,6 +7,16 @@
 # repository. A github OAuth token must be available in the evironment
 # variable GH_TOKEN and is set up through the .travis.yml
 # env:global:secure parameter (encrypted with travis-ci's public key)/
+#
+# Additional environment variables set in .travis.yml
+#  GH_REPOSITORY     repo to full from and push to
+#  GH_DOC_BRANCH     branch from which the docs are built
+#  GIT_CI_USER       name of the user to push docs as
+#  GIT_CI_EMAIL      email of the user to push docs as
+#  MDA_DOCDIR        path to the docdir from top of repo
+#
+# NOTE: If any of these environment variables are not set or 
+#       empty then the script will exit with and error (-o nounset).
 
 set -o errexit -o nounset
 
@@ -16,27 +26,28 @@ function die () {
     exit $err
 }
 
-DOCDIR="package/doc/html"
-REPOSITORY="github.com/MDAnalysis/mdanalysis.git"
-
 rev=$(git rev-parse --short HEAD)
 
+# the following tests should be superfluous because of -o nounset
 test -n "${GH_TOKEN}" || die "GH_TOKEN is empty: need OAuth GitHub token to continue" 100
-cd $DOCDIR || die "Failed to 'cd $DOCDIR'. Run from the top level of the repository"
+test -n "${GH_REPOSITORY}" || die "GH_REPOSITORY must be set in .travis.yml" 100
+test -n "${MDA_DOCDIR}" || die "MDA_DOCDIR must be set in .travis.yml" 100
+
+cd ${MDA_DOCDIR} || die "Failed to 'cd ${MDA_DOCDIR}'. Run from the top level of the repository"
 
 git init
-git config user.name "Travis CI"
-git config user.email "[email protected]"
+git config user.name "${GIT_CI_USER}"
+git config user.email "${GIT_CI_EMAIL}"
 
-git remote add upstream "https://${GH_TOKEN}@${REPOSITORY}"
-git fetch upstream
+git remote add upstream "https://${GH_TOKEN}@${GH_REPOSITORY}"
+git fetch --depth 50 upstream ${GH_DOC_BRANCH} gh-pages
 git reset upstream/gh-pages
 
 touch .
 touch .nojekyll
 
 git add -A .
-git commit -m "rebuild html docs with sphinx at ${rev}"
-git push upstream HEAD:gh-pages
+git commit -m "rebuilt html docs from branch ${GH_DOC_BRANCH} with sphinx at ${rev}"
+git push -q upstream HEAD:gh-pages