OAuth tokens for doc deployment

In order for Travis CI to manipulate GitHub repositories one needs to provide authorization. This can be done with GitHub OAuth tokens. A OAuth token is issued by a person (e.g., @orbeckst), can be limited in scope (e.g., only public repos), and grants the same permissions that the person has (limited by the scope).

Notes on how to use OAuth tokens in the management of MDAnalysis doc deployment had previously been collected in issue #386.

Automatic doc deployment

Following Automatically Update Github Pages with Travis Example seems straighforward enough in order to have travis-ci build the sphinx docs and then push them to the gh-pages branch.

Potential solutions

• Automatically Update Github Pages with Travis Example
• Auto-deploying built products to gh-pages with Travis
• awestruct gh deployment notes

Using OAuth for doc deployment

1. generated OAUTH token (limit scope to public_repo access; I used the tokens web interface but can also be done via curl as described in the awestruct gh deployment notes). IMPORTANT: You MUST get the token at this stage and save it to a file; this is the only time that you get to see the token. For the following, we call this file github_OAUTH_token_SECRET. KEEP THE TOKEN SECRET, never commit!!
2. encrypt for travis with the travis client:

gem2.0 install travis
travis encrypt GH_TOKEN=`cat ./github_OAUTH_token_SECRET`

yields the entry for the .travis.yml file:

 secure: "HIj3p+p2PV8DBVg/KGUx6n83KwB0ASE5FwOn0SMB9zxnzAqe8sapwdBQdMdq0sXB7xT1spJqRxuxOMVEVn35BNLu7bxMLfa4287C8YXcomnvmv9xruxAsjsIewnNQ80vtPVbQddBPxa4jKbqgPby5QhhAP8KANAqYe44pIV70fY="

(This is encrypted with the travis public key. For more details, see Travis CI: Encryption keys.) 3. add lines to .travis.yml along the lines of

script:
  - ./testsuite/MDAnalysisTests/mda_nosetests -v --with-coverage --cover-package MDAnalysis --processes=2 --process-timeout=120 --with-memleak
  - coveralls
  - test $TRAVIS_PULL_REQUEST == "false" && test $TRAVIS_BRANCH == "develop" && cd package/doc/sphinx && make clean html

after_success:
  - test $TRAVIS_PULL_REQUEST == "false" && test $TRAVIS_BRANCH == "develop" && bash maintainer/deploy.sh

env:
   global:
      secure: "HIj3p+p2PV8DBVg/KGUx6n83KwB0ASE5FwOn0SMB9zxnzAqe8sapwdBQdMdq0sXB7xT1spJqRxuxOMVEVn35BNLu7bxMLfa4287C8YXcomnvmv9xruxAsjsIewnNQ80vtPVbQddBPxa4jKbqgPby5QhhAP8KANAqYe44pIV70fY="

(We want to build the developer docs when we push an update to the developer branch.)