Deploy built documentation to GitHub gh-pages from Travis CI

.gitignore

@@ -87,3 +87,7 @@ ENV/
 
 # Rope project settings
 .ropeproject
+
+/.travis_ci_gh_pages_deploy_key
+/.travis_ci_gh_pages_deploy_key.pub
+/gh-pages

.travis-deploy-doc.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without any warranty.
+set -e
+if [[ "${TRAVIS_PULL_REQUEST}" == "false" && "${TRAVIS_BRANCH}" == "${DEPLOY_DOC_FROM_BRANCH}" && -r .travis_ci_gh_pages_deploy_key ]]; then
+    if [[ -z "${DEPLOY_DOC_TO_REPOSITORY}" ]]; then
+        DEPLOY_DOC_TO_REPOSITORY="${TRAVIS_REPO_SLUG}"
+    fi
+    chmod 600 .travis_ci_gh_pages_deploy_key
+    eval `ssh-agent -s`
+    ssh-add .travis_ci_gh_pages_deploy_key
+    rm -Rf gh-pages
+    git clone --depth 1 git@github.com:${DEPLOY_DOC_TO_REPOSITORY}.git --depth 1 --branch=gh-pages gh-pages
+    BUILT_DOCS_DIR=`cd docs/build/html && pwd`
+    cd gh-pages
+    rm -Rf ./${DEPLOY_DOC_TO_DIRECTORY}/*
+    mkdir -p ./${DEPLOY_DOC_TO_DIRECTORY}
+    cp -R $BUILT_DOCS_DIR/* ./${DEPLOY_DOC_TO_DIRECTORY}/
+    git add --all .
+    git config user.name "Travis CI"
+    git config user.email "nobody@example.org"
+    if git commit -m "Automatic upload of documentation built from ${TRAVIS_COMMIT}"; then
+	git push origin gh-pages
+    fi
+fi

.travis-install.sh

@@ -1,4 +1,8 @@
 #! /bin/sh
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without any warranty.
 set -e
 cd $HOME
 if [ ! -x SageMath/sage ] ; then 

.travis-test.sh

@@ -1,4 +1,8 @@
 #! /bin/sh
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without any warranty.
 set -e
 $HOME/SageMath/sage -pip install --upgrade --no-index -v .
 $HOME/SageMath/sage setup.py test

.travis.yml

@@ -1,26 +1,25 @@
+# Copying and distribution of this file, with or without modification,
+# are permitted in any medium without royalty provided the copyright
+# notice and this notice are preserved.  This file is offered as-is,
+# without any warranty.
 language: python
-
-env:
-  - CACHE_NAME=7.1 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.1-Ubuntu_12.04-x86_64.tar.bz2
-  - CACHE_NAME=7.2 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.2-Ubuntu_12.04-x86_64.tar.bz2
-  - CACHE_NAME=7.3 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.3-Ubuntu_12.04-x86_64.tar.bz2
-  - CACHE_NAME=7.4 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.4-Ubuntu_12.04-x86_64.tar.bz2
-
 matrix:
-  allow_failures:
-  - env: CACHE_NAME=7.1 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.1-Ubuntu_12.04-x86_64.tar.bz2
-
+  include:
+  - env: CACHE_NAME=7.6 DEPLOY_DOC_FROM_BRANCH=master DEPLOY_DOC_TO_DIRECTORY=/ SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.6-Ubuntu_12.04-x86_64.tar.bz2
+  - env: CACHE_NAME=7.5.1 SAGE_SERVER=http://mirrors.xmission.com/sage/ SAGE_IMAGE=linux/64bit/sage-7.5.1-Ubuntu_12.04-x86_64.tar.bz2
 install:
-  - ./.travis-install.sh
-
+- ./.travis-install.sh
 script:
-  - ./.travis-test.sh
-
+- ./.travis-test.sh
 cache:
   directories:
-    - $HOME/SageMath
-    - $HOME/.cache/matplotlib
+  - $HOME/SageMath
+  - $HOME/.cache/matplotlib
   timeout: 1000
-
 before_cache:
- - rm -Rf $HOME/SageMath/logs $HOME/SageMath/.BUILDSTART
+- rm -Rf $HOME/SageMath/logs $HOME/SageMath/.BUILDSTART
+after_success:
+- ./.travis-deploy-doc.sh
+before_script:
+- openssl aes-256-cbc -K $encrypted_f96cc3b3888c_key -iv $encrypted_f96cc3b3888c_iv
+  -in .travis_ci_gh_pages_deploy_key.enc -out .travis_ci_gh_pages_deploy_key -d || true

README.rst

@@ -103,6 +103,9 @@ structure as we do here:
 Travis CI integration
 ---------------------
 
+.. image:: https://travis-ci.org/sagemath/sage_sample.svg?branch=master
+    :target: https://travis-ci.org/sagemath/sage_sample
+
 Scripts that run ``make test`` on various SageMath versions on the
 Travis CI system are included.
 https://docs.travis-ci.com/user/for-beginners explains how to enable
@@ -113,3 +116,80 @@ SageMath mirror.  Edit ``.travis-install.sh`` if some optional or
 experimental SageMath packages need to be installed prior to running
 your package.  Edit ``.travis.yml`` to change the list of SageMath
 versions used.
+
+Automatically deploying documentation to GitHub pages using Travis CI
+---------------------------------------------------------------------
+
+ * First do the steps described above to enable Travis CI integration
+   of your GitHub-hosted project.
+
+ * If you don't already have GitHub pages for your project: Create and
+   checkout a branch ``gh-pages`` in your repository and put an empty
+   file ``.nojekyll`` in it.  (See
+   https://help.github.com/articles/files-that-start-with-an-underscore-are-missing/)::
+   Commit it and push it to GitHub::
+
+    $ git clone --single-branch --depth 1 https://github.com/USER/PROJECT.git gh-pages
+    $ cd gh-pages
+    $ git checkout --orphan gh-pages
+    $ git rm -rf .
+    $ touch .nojekyll
+    $ git add .nojekyll
+    $ git commit -m "Initial commit"
+    $ git push -u origin gh-pages
+    $ cd ..
+
+ * (Back in your working copy:) Generate a new ssh key pair with an
+   empty passphrase::
+
+    $ ssh-keygen -t dsa -f .travis_ci_gh_pages_deploy_key
+
+ * Add the public ssh key (contents of the file
+   ``.travis_ci_gh_pages_deploy_key.pub``) to your GitHub repository
+   as a deploy key (Settings/Deploy keys/Add deploy key).
+   Title: Key for deploying documentation to GitHub pages.
+   Check Allow write access.
+
+ * Install the Travis CI command-line client from
+   https://github.com/travis-ci/travis.rb::
+
+    $ gem install travis
+
+ * Log in to Travis CI using your GitHub credentials::
+
+    $ travis login
+
+ * Encrypt the private ssh key, add the decryption keys
+   as secure environment variables to Travis CI, and
+   add code to ``.travis.yml`` to decrypt it::
+
+    $ travis encrypt-file .travis_ci_gh_pages_deploy_key --add before_script
+
+ * Add the encrypted private ssh key to the repository::
+
+    $ git add .travis_ci_gh_pages_deploy_key.enc
+
+ * Have git ignore the other keys (and the gh-pages directory)::
+
+    $ echo >> .gitignore
+    $ echo "/.travis_ci_gh_pages_deploy_key" >> .gitignore
+    $ echo "/.travis_ci_gh_pages_deploy_key.pub" >> .gitignore
+    $ echo "/gh-pages" >> .gitignore
+    $ git add .gitignore
+
+ * Optionally, edit ``.travis.yml`` to adjust variables ``DEPLOY_DOC_...``
+
+ * Commit all changes to GitHub.  The Travis CI build should then run
+   automatically and deploy it::
+
+    $ git add .travis.yml
+    $ git commit -m "Deploy built documentation to GitHub"
+    $ git push
+
+ * The deployed documentation will be available at:
+   https://USER.github.io/PROJECT/
+   This can be customized by changing ``DEPLOY_DOC_TO_DIRECTORY=/``
+   to another directory in ``.travis.yml``
+   For example, setting ``DEPLOY_DOC_TO_DIRECTORY=doc/html`` will make
+   the deployed documentation available at:
+   https://USER.github.io/PROJECT/doc/html/