add doc stuff

.travis.yml

@@ -18,6 +18,7 @@ env:
     - GIT_CI_USER=TravisCI
     - GIT_CI_EMAIL=TravisCI@mdanalysis.org
     - MDA_DOCDIR=${TRAVIS_BUILD_DIR}/package/doc/html/html
+    - MAINTAIN_DIR=${TRAVIS_BUILD_DIR}/maintainer
     # Set default python version to avoid repetition later
     - PYTHON_VERSION=3.6
     - BUILD_DOCS=false
@@ -54,7 +55,7 @@ matrix:
            BUILD_DOCS=true
            BUILD_CMD="cd ${TRAVIS_BUILD_DIR}/package && python setup.py build_ext --inplace"
            INSTALL_HOLE="false"
-           PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx==1.8.5 sphinx-sitemap sphinx_rtd_theme"
+           PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx==1.8.5 sphinx-sitemap sphinx_rtd_theme msmb_theme==1.2.0"
 
     - env: NAME="Lint"
            PYLINTRC="${TRAVIS_BUILD_DIR}/package/.pylintrc"
@@ -131,6 +132,12 @@ after_success:
       codecov; \
     fi
   # can't use test here since this leads to travis fails even though the build passes
-  - if [[ ${TRAVIS_PULL_REQUEST} == "false" ]] && [[ ${BUILD_DOCS} == "true" ]] && [[ ${TRAVIS_BRANCH} == ${GH_DOC_BRANCH} ]]; then
-            bash ${TRAVIS_BUILD_DIR}/maintainer/deploy_docs.sh;
+  - |
+    if [[ ${TRAVIS_PULL_REQUEST} == "false" ]] && [[ ${BUILD_DOCS} == "true" ]] && [[ ${TRAVIS_BRANCH} == ${GH_DOC_BRANCH} ]]; then
+      python -c 'import os,sys,fcntl; flags = fcntl.fcntl(sys.stdout, fcntl.F_GETFL); fcntl.fcntl(sys.stdout, fcntl.F_SETFL, flags&~os.O_NONBLOCK);'
+      cd ${TRAVIS_BUILD_DIR}/package/MDAnalysis
+      export VERSION=$(python -c "import version; print(version.__version__)")
+      cd -
+      bash ${TRAVIS_BUILD_DIR}/maintainer/deploy_docs_via_travis.sh;
     fi
+

maintainer/deploy_docs_via_travis.sh

@@ -0,0 +1,72 @@
+#!/bin/bash
+# Deploying docs from travis-ci.
+# See https://github.com/MDAnalysis/mdanalysis/issues/386
+# Script based on https://github.com/steveklabnik/automatically_update_github_pages_with_travis_example
+
+# Run this script from the top-level of the checked out git
+# 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
+#  MAINTAIN_DIR      path to maintainer/
+#
+# 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
+
+function die () {
+    local msg="$1" err=${2:-1}
+    echo "ERROR: $msg [$err]"
+    exit $err
+}
+
+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
+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
+test -n "${MAINTAIN_DIR}" || die "MAINTAIN_DIR must be set in .travis.yml" 100
+test -n "${VERSION}" || die "VERSION must be set in .travis.yml" 100
+
+
+cd ${MDA_DOCDIR} || die "Failed to 'cd ${MDA_DOCDIR}'. Run from the top level of the repository"
+
+# move into $version subdirectory
+mkdir ../${VERSION} && mv * ../${VERSION}
+
+git init
+git config user.name "${GIT_CI_USER}"
+git config user.email "${GIT_CI_EMAIL}"
+
+mv ../${VERSION} $VERSION
+
+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
+
+echo $VERSION
+echo "ls *"
+ls *
+git add -A ${VERSION}/
+git add .nojekyll
+
+python ${MAINTAIN_DIR}/update_versions_json.py
+git add versions.json
+
+# check for anything to commit
+# https://stackoverflow.com/questions/3878624/how-do-i-programmatically-determine-if-there-are-uncommited-changes
+git diff-index --quiet HEAD -- || git commit -m "rebuilt html docs from branch ${GH_DOC_BRANCH} with sphinx at ${rev}"
+git push -q upstream HEAD:gh-pages
+
+

maintainer/update_versions_json.py

@@ -0,0 +1,41 @@
+import json
+import os
+
+try:
+    from urllib.request import urlopen
+except ImportError:
+    from urllib2 import urlopen
+
+URL = "https://www.mdanalysis.org/mdanalysis/"
+
+VERSION = os.environ['VERSION']
+url = os.path.join(URL, 'versions.json')
+try:
+    data = urlopen(url).read().decode()
+    versions = json.loads(data)
+except:
+    try:
+        with open('versions.json', 'r') as f:
+            versions = json.loads(f)
+    except:
+        versions = []
+
+existing = [item['version'] for item in versions]
+already_exists = VERSION in existing
+
+if not already_exists:
+    latest = 'dev' not in VERSION
+    if latest:
+        for ver in versions:
+            ver['latest'] = False
+
+    versions.append({
+        'version': VERSION,
+        'display': VERSION,
+        'url': os.path.join(URL, VERSION),
+        'latest': latest
+        })
+
+with open("versions.json", 'w') as f:
+    json.dump(versions, f, indent=2)
+

package/MDAnalysis/version.py

@@ -68,3 +68,4 @@
 
 #: Release of MDAnalysis as a string, using `semantic versioning`_.
 __version__ = "2.0.0-dev0"  # NOTE: keep in sync with RELEASE in setup.py
+release = False

package/doc/sphinx/source/conf.py

@@ -15,6 +15,7 @@
 import os
 import platform
 import datetime
+import msmb_theme  # for little versions pop-up
 # https://sphinx-rtd-theme.readthedocs.io/en/stable/
 import sphinx_rtd_theme
 
@@ -123,7 +124,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'msmb_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -156,8 +157,15 @@
     'titles_only': False,
 }
 
+html_context = {
+    'versions_json_url': 'https://lilyminium.github.io/mdanalysis/versions.json'
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = ['_themes',]
+html_theme_path = [
+    msmb_theme.get_html_theme_path(),
+    sphinx_rtd_theme.get_html_theme_path()
+]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".