version switcher dropdown

.github/define_versions.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# List of documentation versions to keep.
+# (should include all versions in switcher.json)
+# Adding future versions will capture that version
+# once it appears in the downloaded gh-pages branch.
+
+versions=
+
+# existing versions (to be kept)
+versions+=" 1.0.0"
+versions+=" 1.0.1"
+versions+=" 1.0.3"
+versions+=" 1.0.4"
+
+# future versions (only expected release tags)
+versions+=" 1.0.5"
+versions+=" 1.0.6"
+versions+=" 1.0.7"
+
+export versions
+
+# update file `docs/source/_static/switcher.json` before each new release

.github/workflows/pages.yml

@@ -25,7 +25,7 @@ defaults:
 
 jobs:
 
-  pages:
+  docs:
     runs-on: ubuntu-latest
 
     steps:
@@ -63,50 +63,46 @@ jobs:
         run: |
           echo "TEMPDIR=$(mktemp -d)" >> ${GITHUB_ENV}
           echo "VERSION=$(./setup.py --version)" >> ${GITHUB_ENV}
-          echo "LATEST_RELEASE=1.0.4" >> ${GITHUB_ENV}
 
       - name: Show Environment variables
         run: |
           echo "TEMPDIR=${TEMPDIR}"
           echo "VERSION=${VERSION}"
 
-      - name: Get existing gh-pages branch
+      - name: Re-build the master directory (contains all documentation versions)
         run: |
-          wget https://github.com/prjemian/pysumreg/archive/refs/heads/gh-pages.zip
-          unzip -q -o -d "${TEMPDIR}" ./gh-pages.zip
-          pushd "${TEMPDIR}/pysumreg-gh-pages"
-          tar cf - * | (cd .. && tar xf -)
-          cd ..
-          /bin/rm -rf ./pysumreg-gh-pages
-          /bin/rm -rf dev *.dev* latest
-          ln -s "./${LATEST_RELEASE}" ./latest
-          touch .nojekyll
-          ls -lAFgh
-          popd
+          cp .github/index.html "${TEMPDIR}"
 
-          # make the switcher file
-          python ./.github/make_switcher.py | tee docs/source/_static/switcher.json
+          cd "${TEMPDIR}"
+          mv build/html "${VERSION}"
+          /bin/rm -rf build
+          ln -s "./${VERSION}" dev
 
-      - name: Sphinx
-        run: |
-          sphinx-build -M html ./docs/source "${TEMPDIR}/build"
+          # add previous documentation (built versions)
+          wget https://github.com/prjemian/pysumreg/archive/refs/heads/gh-pages.zip
+          unzip -q gh-pages.zip
+          /bin/rm gh-pages.zip
+
+          source ../define_versions.sh
+          for v in ${versions}
+            do
+                if [ -d "pysumreg-gh-pages/${v}" ]
+                  then
+                      echo "directory 'pysumreg-gh-pages/${v}' exists"
+                      mv "pysumreg-gh-pages/${v}" ./
+                      latest="${v}"
+                  fi
+            done
+          echo "latest=${latest}"
+          ln -s "./${latest}" ./latest
+
+          /bin/rm -rf pysumreg-gh-pages
 
-      - name: Add new gh-pages content
+      - name: Info
         run: |
-          # get the new docs
-          pushd "${TEMPDIR}"
-          mv ./build/html "./${VERSION}"
-          ln -s "./${VERSION}" ./dev
-          /bin/rm -rf ./build
-          popd
-
-          # get the redirect page
-          cp ./.github/index.html "${TEMPDIR}"
-
-          # diagnostic
-          ls -lAFgh "${TEMPDIR}"
-          cat "${TEMPDIR}/index.html"
-          cat "${TEMPDIR}/_static/switcher.json"
+          cd "${TEMPDIR}"
+          echo "pwd=$(pwd)"
+          ls -laFGh
 
       - name: Deploy (to gh-pages branch) only on demand
         uses: peaceiris/actions-gh-pages@v3

CHANGES.rst

@@ -20,6 +20,16 @@ Change History
 
    release expected TBA
 
+1.0.5
+******
+
+release expected 2023-02-01
+
+Enhancements
+--------------
+
+Provide older documentation versions from dropdown menu.
+
 1.0.4
 ******
 

docs/source/_static/css/custom.css

@@ -0,0 +1,25 @@
+/* Style the link marked: latest */
+.version-switcher__container a[data-version-name*="latest"] {
+    background-color: lightgreen;
+ }
+
+ /* Style the link marked: dev */
+ .version-switcher__container a[data-version="dev"] {
+    background-color: var(--pst-color-secondary);
+ }
+
+
+ /* Style the link marked: redirect */
+ .version-switcher__container a[data-version="redirect"] {
+    background-color: bisque;
+ }
+
+ /* Style all links with a specific subset of versions */
+ .version-switcher__container a[data-version="1.0.3"] {
+    background-color: rgb(247, 231, 233);
+ }
+ .version-switcher__container a[data-version="1.0.3"],
+ .version-switcher__container a[data-version="1.0.1"],
+ .version-switcher__container a[data-version="1.0.0"] {
+    background-color: lightpink;
+ }

docs/source/_static/switcher.json

@@ -10,17 +10,14 @@
         "url": "https://prjemian.github.io/pysumreg/1.0.4"
     },
     {
-        "name": "1.0.3",
         "version": "1.0.3",
         "url": "https://prjemian.github.io/pysumreg/1.0.3"
     },
     {
-        "name": "1.0.1",
         "version": "1.0.1",
         "url": "https://prjemian.github.io/pysumreg/1.0.1"
     },
     {
-        "name": "1.0.0",
         "version": "1.0.0",
         "url": "https://prjemian.github.io/pysumreg/1.0.0"
     }

docs/source/conf.py

@@ -4,6 +4,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import configparser
+import json
 import pathlib
 import sys
 
@@ -13,9 +14,26 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+gh_org = "prjemian"
+project = "pysumreg"
 release = pysumreg.__version__
 version = ".".join(release.split(".")[:2])
 
+# fmt: off
+switcher_file = "_static/switcher.json"
+switcher_json_url = (
+    "https://raw.githubusercontent.com/"
+    f"{gh_org}/{project}/"
+    "main/docs/source"
+    f"/{switcher_file}"
+)
+with open(switcher_file) as fp:
+   switcher_version_list = [
+      v["version"]  # to match with ``release`` (above)
+      for v in json.load(fp)
+   ]
+# fmt: on
+
 root_path = pathlib.Path(__file__).parent.parent.parent
 parser = configparser.ConfigParser()
 parser.read(root_path / "setup.cfg")
@@ -26,6 +44,7 @@
 author = metadata["author"]
 description = metadata["description"]
 rst_prolog = f".. |author| replace:: {author}"
+github_url = f"https://github.com/{gh_org}/{project}",
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -49,6 +68,9 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_css_files = [
+    "css/custom.css",
+]
 html_static_path = ["_static"]
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {
@@ -59,8 +81,8 @@
    },
    "navbar_start": ["navbar-logo", "version-switcher"],
    "switcher": {
-      "json_url": "https://prjemian.github.io/pysumreg/_static/switcher.json",
-      "version_match": "dev" if ".dev" in release else release,
+      "json_url": switcher_json_url,
+      "version_match": release if release in switcher_version_list else "dev"
    }
 }
 html_title = "PySumReg"