Update Sphinx version and migrate to sphinx-multiversion CLEWS-33782

bin/sphinx_push_ghpages.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+
+# This script replicates basic `sphinx-versioning push` functionality for
+# sphinx-multiversion. It should be run from the base of the git repo.
+# It's largely based on sphinxcontrib-versioning's code:
+# https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/920edec0ac764081b583a2ecf4e6952762b9dbf2/sphinxcontrib/versioning/__main__.py#L332
+
+set -e -u -o pipefail
+
+# Branch to push the generated docs to.
+PAGES_BRANCH=gh-pages
+# Which branch to store at the root of the docs. Analogous to scv_root_ref:
+# https://sphinxcontrib-versioning.readthedocs.io/en/latest/settings.html#cmdoption-r
+ROOT_REF=development
+# Files to keep in the repo. Analogous to scv_grm_exclude:
+# https://sphinxcontrib-versioning.readthedocs.io/en/latest/settings.html#cmdoption-e
+KEEP_FILES=(.nojekyll CNAME README.md shippable.yml)
+
+# get origin repo. assumes fetch and pull locations are the same.
+REPO=$(git remote -v | grep origin | awk 'NR==1 { print $2 }')
+TMPDIR=$(mktemp -d ./tmp-sphinx.XXX)
+
+
+## prepare helper repo
+
+# clone into temp dir
+echo -e "\n-> cloning $REPO to temp dir $TMPDIR..."
+cd "$TMPDIR"
+git clone "$REPO" --quiet --depth=1 --branch="${PAGES_BRANCH}" .
+# remove old files
+git rm -rf --quiet .
+# restore some files we want to keep. note: using bash array syntax.
+git reset --quiet HEAD -- "${KEEP_FILES[@]}"
+git checkout -- "${KEEP_FILES[@]}"
+
+
+## build docs
+
+echo -e "\n-> building docs..."
+# 'sphinx-multiversion ../docs .' fails, so we just cd back out for this step.
+cd ..
+sphinx-multiversion docs "$TMPDIR"
+cd "$TMPDIR"
+
+# With sphinxcontrib-versioning, we would generate a separate directory of docs
+# for each version tag and branch, but also have the 'development' branch's
+# docs at the top level.  sphinx-multiversion only generates the separate
+# directories. To avoid breaking links, we copy the the root ref docs (i.e.,
+# the development branch docs) to the parent directory containing all docs.
+echo -e "\n-> copying root ref ($ROOT_REF) to docs root..."
+cp -R "${ROOT_REF}/." .
+
+echo -e "\n-> checking for changes..."
+git add .
+# ignore trivial changes (.doctrees and .buildinfo files are always modified
+# when rebuilding the docs). Notes:
+# - '|| true' is needed because when grep fails to match something, it returns
+#   a non-zero exit code, which causes the script to fail due to the 'pipefail'
+#   setting.
+# - this logic differs from sphinxcontrib-versioning slightly. SCV ignores
+#   searchindex.js but not .buildinfo. I didn't notice searchindex.js being
+#   regenerated unnecessarily, but did see that happening with .buildinfo files.
+CHANGED=$(git diff HEAD --no-ext-diff --name-status | grep -v '^M.*\.doctrees/' | grep -v '^M.*\.buildinfo$' || true)
+if [ -z "$CHANGED" ]; then
+  echo -e "\n-> no changes, done!"
+  exit 0
+else
+  echo -e "\n-> found changed files:"
+  echo "$CHANGED"
+fi
+
+echo -e "\n-> committing change..."
+git commit -m "sphinx_push_ghpages.sh: autocommit $(date '+%Y-%m-%d %H:%M:%S')"
+
+echo -e "\n-> pushing update..."
+git push origin "$PAGES_BRANCH"
+
+echo -e "\n-> done!"

docs/README.md

@@ -23,15 +23,15 @@ open up and view in a web browser.
 
 ## Automatic builds
 
-Every time continuous integration runs it should be re-building the
-documentation for any currently-open branches and pushing the result to the
-`gh-pages` branch. If you edit any documentation pages or docstrings, it should
-be a part of the Pull Request review process that you navigate to your feature
-branch's built documentation and verify that the changes are as intended.
-
-Note that branches aren't listed in the version-selector widget (since we don't
-want to show it to external users), but you can navigate directly to it:
+Every time continuous integration runs, it re-builds the documentation for any
+currently-open branches and pushes the result to the `gh-pages` branch (even
+for unmerged pull requests). If you edit any documentation pages or docstrings,
+navigate to your feature branch's documentation and verify that the changes are
+as intended.
+
+Branches aren't listed in the version-selector widget (since we don't want to
+show them to external users). You have to edit the URL manually:
 `https://developers.gro-intelligence.com/<YOUR-BRANCH-NAME-HERE>/index.html`
 
 If anything in continuous integration fails, the documentation building step is
-skipped.
+skipped. CI calls `bin/sphinx_push_ghpages.sh` to build and push the docs.

docs/_static/css/banner.css

@@ -1,29 +1,26 @@
-/* https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/master/sphinxcontrib/versioning/_static/banner.css */
-
-.scv-banner {
-  padding: 3px;
-  border-radius: 2px;
-  font-size: 80%;
-  text-align: center;
-  color: white;
-  background: #2980B9;
+/* based on https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/master/sphinxcontrib/versioning/_static/banner.css */
+
+.version-banner {
+    padding: 3px;
+    border-radius: 2px;
+    font-size: 80%;
+    text-align: center;
+    color: white;
+    background: #d40 linear-gradient(-45deg,
+        rgba(255, 255, 255, 0.2) 0%,
+        rgba(255, 255, 255, 0.2) 25%,
+        transparent 25%,
+        transparent 50%,
+        rgba(255, 255, 255, 0.2) 50%,
+        rgba(255, 255, 255, 0.2) 75%,
+        transparent 75%,
+        transparent
+    );
+    background-size: 28px 28px;
+    /* from sphinx_rtd_theme selector: use bluish background */
+    background-color: #2980B9;
 }
 
-.scv-banner > a {
-  color: white;
+.version-banner a, .version-banner a:visited {
+    color: white;
 }
-
-
-.scv-bizstyle {
-  background-color: #336699;
-}
-
-
-.scv-classic {
-  text-align: center !important;
-}
-
-
-.scv-traditional {
-  text-align: center !important;
-}

docs/_static/css/custom-theme.css

@@ -231,8 +231,3 @@ a > code {
   font-weight: 500;
   color: #9b9b9e;
 }
-
-/* hide branches from version switcher */
-.rst-other-versions dl:last-child {
-  display: none;
-} 

docs/_templates/page.html

@@ -0,0 +1,24 @@
+{#
+See https://holzhaus.github.io/sphinx-multiversion/master/templates.html#version-banners
+
+TODO(jli): The example above nicely links to the latest *released* version,
+rather than development. That's probably the way to go, since almost all users
+should be using our PyPI package. However, the 'latest_version' variable seems
+to be hardcoded to "master". Would be great if it actually used the latest
+released tag instead.
+
+Also see: https://github.com/Holzhaus/sphinx-multiversion/issues/58
+#}
+
+{% extends "!page.html" %}
+{% block body %}
+{% if current_version and current_version.name != 'development' %}
+<p class="version-banner">
+  <strong>Note:</strong>
+  This document is for an older version of the Gro API Client.
+  Please see the <a href="{{ vpathto('development') }}">latest documentation</a>.
+</p>
+{% endif %}
+{{ super() }}
+{% endblock %}%
+

docs/_templates/versions.html

@@ -0,0 +1,34 @@
+{#
+Based on https://holzhaus.github.io/sphinx-multiversion/master/templates.html#readthedocs-theme
+This is the template for the version-selector widget at the bottom left corner.
+We list the tags as "Releases", and we include the "development" branch at the
+end of the list.
+#}
+{%- if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags %}
+    <dl>
+      <dt>Releases</dt>
+      {%- for item in versions.tags %}
+      <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+      {%- endfor %}
+
+      {# we also list the development branch here so that it's always accessible. #}
+      {%- if versions.branches %}
+        {%- for item in versions.branches %}
+          {%- if item.name == 'development' %}
+            <dd><a href="{{ item.url }}">{{ item.name }}</a></dd>
+          {%- endif %}
+        {%- endfor %}
+      {%- endif %}
+    </dl>
+    {%- endif %}
+  </div>
+</div>
+{%- endif %}

docs/conf.py

@@ -12,7 +12,6 @@
 #
 import os
 import sys
-import re
 sys.path.insert(0, os.path.abspath('..'))
 
 
@@ -36,7 +35,8 @@
     'sphinx.ext.extlinks',
     'sphinx.ext.napoleon',
     'sphinx.ext.viewcode',
-    'recommonmark'
+    'recommonmark',
+    'sphinx_multiversion'
 ]
 
 source_suffix = {
@@ -84,16 +84,24 @@
 
 master_doc = 'index'
 
-# Do not delete these files:
-scv_grm_exclude = ('README.md', '.gitignore', '.nojekyll', 'CNAME', 'shippable.yml*')
-scv_show_banner = True
-scv_banner_main_ref = 'development'
-scv_root_ref = 'development'
 
-# still build other branches, but hide the version selectors in _static/css/custom-theme.css.
-# Uncomment this line to stop building them altogether:
-# scv_whitelist_branches = ('development',)
+# -- sphinx-multiversion options ---------------------------------------------
 
-# Omit versions before docs style was finalized
-# TODO: https://stackoverflow.com/questions/26141851/let-sphinx-use-version-from-setup-py
-scv_whitelist_tags = (re.compile(r'^(?!.*(v1.40.0|v1.40.1|v1.40.2|v1.40.3|v1.40.4|v1.40.5)).*$'),)
+# v1.40.6 (from 2019-12-19) is the first version with finalized docs style.
+# so, we ignore all other releases that preceded that.
+smv_tag_whitelist = r'^v(?!1\.40\.[012345]).+$'
+
+# By default, sphinx-multiversion doesn't build remote branches. We want to
+# build all branches, so we sent the pattern to something that matches
+# everything.
+smv_remote_whitelist = r'.'
+
+# Exclude the 'HEAD' ref from being built. Due to building remote refs with
+# smv_remote_whitelist, SMV will build the remotes/origin/HEAD ref. This is
+# equivalent to the 'development' branch, so no need to build it again.
+smv_branch_whitelist = r'^(?!HEAD).*$'
+
+# Note: see bin/sphinx_push_ghpages.sh for how we push new documentation to
+# GitHub Pages. Some options related to pushing docs changes that used to be
+# set here for sphinxcontrib-versioning are now configured in the script, since
+# sphinx-multiversion doesn't have built-in support for pushing changes.