Publish documentation to GitHub Pages

The old pythonhosted.org docs hosting is deprecated now, so we needed
a new hosting site.  Unfortunately, RTD can't handle our use cases
(customizations, requiring C libraries).  Instead, we use GitHub pages.

Every push to master (or an `infra/` branch for testing) will push
documentation to the `/latest` subdirectory of the gh-pages site,
while every tag build will push to the `/stable` directory.

Author: traviscibot

.travis.yml

@@ -21,6 +21,8 @@ before_install: skip
 stages:
 - verify
 - test
+- name: deploy latest docs
+  if: (branch = master OR branch =~ ^infra/$) AND type = push
 - name: deploy
   if: tag is PRESENT
 
@@ -44,9 +46,30 @@ jobs:
     - source ./.travis/lib-util.sh
     - util::docker-run $DISTRO ./.travis/verify.sh
 
+  - stage: deploy latest docs
+    script: skip
+    env:
+    - DISTRO=fedora:rawhide
+    - PYTHON="3"
+    - secure: L5SpEj5+no20PWwC9Y/XNhAfmUvYiuykwSMa/YyqvUuBjdizzpZcHr7Ego5nMdM1TniTxj4pSTM+GbM0FHCzNmAINSRh9g/D3hheRqlRBacqR0XwC9ZZRvkKvtzwnLh4vYWiauq4AoDeR5U6tkEcay6LjE57iMQcLjcKYBc+Eos=
+    before_deploy:
+    - source ./.travis/lib-util.sh
+    - util::docker-run $DISTRO ./.travis/before-docs-deploy.sh
+
+    deploy:
+    - provider: script
+      script: .travis/docs-deploy.sh travis_docs_build/html latest pythongssapi/python-gssapi
+      skip_cleanup: true
+      on:
+        all_branches: true
+
+
   - stage: deploy
     script: skip
-    env: DISTRO=fedora:rawhide PYTHON="3"
+    env:
+    - DISTRO=fedora:rawhide
+    - PYTHON="3"
+    - secure: L5SpEj5+no20PWwC9Y/XNhAfmUvYiuykwSMa/YyqvUuBjdizzpZcHr7Ego5nMdM1TniTxj4pSTM+GbM0FHCzNmAINSRh9g/D3hheRqlRBacqR0XwC9ZZRvkKvtzwnLh4vYWiauq4AoDeR5U6tkEcay6LjE57iMQcLjcKYBc+Eos=
     before_deploy:
     - source ./.travis/lib-util.sh
     - util::docker-run $DISTRO ./.travis/before-deploy.sh
@@ -55,7 +78,7 @@ jobs:
     deploy:
     - provider: releases
       api_key:
-        secure: e8kjZEY28gWySD5FsnG9CMgeKgFS12gB/xm1Ck1jEgIhYT01VwxvBMHIU7SV/92+aeBao5clN4/qN4P035hD8TShHUMzV7rsmXmqcaCwi3J5sh2hyy4e1PfYAshuX7bxvkfqJSvSonLz0AKHW4pj17yMrTXpWiEioGg0fSLtTHo=
+        secure: fAaSSSjd/nUrIpINBjAT590pGF2nGq3I8ee6aGq6IAFpXoa/9eeN5eyOrE4MYucWCwYcH28c7510n35vuZQQor+UZIDo6l0K5M64/NZE1cZ43zOMjw3yHlrsJG+ohPS7YvjqD8GaFlLhF6ZvWvrPmWeijvs8qAT1eL7QoEG0xBk=
       file_glob: true
       file:
         - tag_build/*
@@ -74,3 +97,10 @@ jobs:
         all_branches: true
       # NB(directxman12): this is a hack.  Check ./.travis/before-deploy.sh for an explanation.
       distributions: "check"
+    
+    - provider: script
+      script: .travis/docs-deploy.sh travis_docs_build/html stable pythongssapi/python-gssapi
+      skip_cleanup: true
+      on:
+        all_branches: true
+

.travis/before-deploy.sh

@@ -1,6 +1,7 @@
 #!/bin/bash -ex
 
 source ./.travis/lib-setup.sh
+source ./.travis/lib-deploy.sh
 
 # build again since I can't figure out how to get travis to recognize the old
 # build in the new container.  The other alternative (besides actually solving
@@ -13,15 +14,7 @@ setup::activate
 yum -y install tar coreutils git
 
 # build the docs
-# the first run is for the docs build, so don't clean up
-pip install -r docs-requirements.txt
-
-# install dependencies so that sphinx doesn't have issues
-# (this actually just installs the whole package in dev mode)
-pip install -e .
-
-# place in a non-standard location so that they don't get cleaned up
-python setup.py build_sphinx --build-dir travis_docs_build
+deploy::build-docs
 
 # NB(directxman12): this is a *terrible* hack, but basically,
 # dpl (the Travis deployer) uses `twine` instead of `setup.py sdist upload`.

.travis/before-docs-deploy.sh

@@ -0,0 +1,14 @@
+#!/bin/bash -ex
+
+source ./.travis/lib-setup.sh
+source ./.travis/lib-deploy.sh
+
+# build again since I can't figure out how to get travis to recognize the old
+# build in the new container.  The other alternative (besides actually solving
+# the issue) is to run the docs build and tarball generation every time.
+
+./.travis/build.sh
+
+setup::activate
+
+deploy::build-docs

.travis/docs-deploy.sh

@@ -0,0 +1,37 @@
+#!/bin/bash -ex
+
+# NB (very important): BE VERY CAREFUL WITH `set -x` FOR THIS FILE.
+# The GitHub token is sensative information, and should never
+# be displayed on in the clear.
+
+source_directory=${1?need <source dir> <target dir> <target repo> [<target branch, default: gh-pages>]}
+target_directory=${2?need <source dir> <target dir> <target repo> [<target branch, default: gh-pages>]}
+target_repo=${3?need <source dir> <target dir> <target repo> [<target branch, default: gh-pages>]}
+target_branch=${4:-gh-pages}
+
+desc=$(git describe --tags)
+
+scratch_dir=$(mktemp -d)
+
+set +x # IMPORTANT
+echo "cloning https://<elided>@github.com/${target_repo}.git#${target_branch} in to ${scratch_dir}/docs..."
+git clone https://${GITHUB_TOKEN}@github.com/${target_repo}.git ${scratch_dir}/docs -b ${target_branch}
+set -x
+
+mkdir -p ${scratch_dir}/docs/${target_directory}
+cp -r ${source_directory}/. ${scratch_dir}/docs/${target_directory}
+echo $desc > ${scratch_dir}/docs/${target_directory}/.from
+pushd $scratch_dir/docs
+git config user.email "deploy@travis-ci.org"
+git config user.name "Deployment Bot (from Travis CI)"
+git add ${target_directory}
+git commit -m "Update ${target_directory} docs in based on ${desc}"
+
+set +x # IMPORTANT
+echo "pushing to https://<elided>@github.com/${target_repo}.git#${target_branch}"
+git push --quiet --force-with-lease origin ${target_branch}:${target_branch}
+set -x
+
+popd
+rm -rf ${scratch_dir}
+echo "done!"

.travis/lib-deploy.sh

@@ -0,0 +1,13 @@
+deploy::build-docs() {
+    # the first run is for the docs build, so don't clean up
+    pip install -r docs-requirements.txt
+
+    # install dependencies so that sphinx doesn't have issues
+    # (this actually just installs the whole package in dev mode)
+    pip install -e .
+
+    # place in a non-standard location so that they don't get cleaned up
+    python setup.py build_sphinx --build-dir travis_docs_build
+
+    echo "travis_docs_build"
+}

README.txt

@@ -21,8 +21,12 @@ Python-GSSAPI provides both low-level and high level wrappers around the GSSAPI
 C libraries.  While it focuses on the Kerberos mechanism, it should also be
 useable with other GSSAPI mechanisms.
 
-Documentation for the latest released version can be found at
-`https://pythonhosted.org/gssapi <https://pythonhosted.org/gssapi>`_.
+Documentation for the latest released version (including pre-release versions)
+can be found at
+`https://pythongssapi.github.io/python-gssapi/stable <https://pythongssapi.github.io/python-gssapi/stable>`_.
+
+Documentation for the latest commit on master can be found at
+`https://pythongssapi.github.io/python-gssapi/latest <https://pythongssapi.github.io/python-gssapi/latest>`_.
 
 Requirements
 ============