docs for several tagged releases

.github/scripts/define_versions.sh

@@ -0,0 +1,24 @@
+#!/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 (typically release tags) to be kept if they exist
+versions=
+
+# existing versions
+versions+=" 1.6.6"
+versions+=" 1.6.8"
+versions+=" 1.6.9"
+
+# future versions (only expected release tags)
+versions+=" 1.6.10"
+versions+=" 1.6.11"
+versions+=" 1.6.12"
+
+export versions
+
+# update file `docs/source/_static/switcher.json` before each new release

.github/workflows/pages.yml

@@ -0,0 +1,121 @@
+name: Publish Sphinx Docs to GitHub Pages
+
+on:
+  # Build the docs on pushes to main branch, PRs to main branch, and new tags.
+  # Publish only on demand.
+  push:
+    branches:
+      - main
+    tags:
+      - '*'  # all tags
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:   # allow manual triggering
+    inputs:
+      deploy:
+        description: 'Deploy documentation'
+        type: boolean
+        required: true
+        default: false
+
+defaults:
+  run:
+    shell: bash -l {0}
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/setup-python@v2
+
+    - name: Checkout
+      uses: actions/checkout@master
+      with:
+        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+
+    - name: Deploy Information
+      if: ${{ github.event.inputs.deploy }}
+      run: |
+        echo "The will be published from this workflow run."
+
+    - name: Install pandoc
+      run: |
+        sudo apt-get update && \
+        sudo apt-get -y install pandoc
+
+    - name: Install Sphinx build requirements
+      run: |
+        pip install -r requirements-sphinx.txt setuptools-scm
+
+    - name: Install our package
+      run: |
+        pip install --no-deps -e .
+
+    - name: Diagnostic
+      run: |
+        echo $(which pandoc)
+        echo $(which sphinx-build)
+
+    - name: Make Temporary Directory for Sphinx content
+      run: |
+        echo "SRC_DIR=$(pwd)" >> ${GITHUB_ENV}
+        echo "TMP_DIR=$(mktemp -d)" >> ${GITHUB_ENV}
+        # next step also creates _version.py file
+        echo "VERSION=$(./setup.py --version)" >> ${GITHUB_ENV}
+
+    - name: Show Environment variables
+      run: |
+        echo "SRC_DIR=${SRC_DIR}"
+        echo "TMP_DIR=${TMP_DIR}"
+        echo "VERSION=${VERSION}"
+
+    - name: Sphinx
+      run: |
+        sphinx-build -M html ./docs/source "${TMP_DIR}/build"
+
+    - name: Re-build the master directory (contains all documentation versions)
+      run: |
+        cp .github/index.html "${TMP_DIR}"
+
+        cd "${TMP_DIR}"
+        mv build/html "${VERSION}"
+        /bin/rm -rf build
+        ln -s "./${VERSION}" dev
+
+        # add previous documentation (built versions)
+        # update the switcher.json file before a new release
+        wget https://github.com/BCDA-APS/apstools/archive/refs/heads/gh-pages.zip
+        unzip -q gh-pages.zip
+        /bin/rm gh-pages.zip
+
+        source "${SRC_DIR}/.github/scripts/define_versions.sh"
+        for v in ${versions}
+          do
+              if [ -d "apstools-gh-pages/${v}" ]
+                then
+                    echo "directory 'apstools-gh-pages/${v}' exists"
+                    mv "apstools-gh-pages/${v}" ./
+                    latest="${v}"
+                fi
+          done
+        echo "latest=${latest}"
+        ln -s "./${latest}" ./latest
+
+        /bin/rm -rf apstools-gh-pages
+
+    - name: Info
+      run: |
+        cd "${TMP_DIR}"
+        echo "pwd=$(pwd)"
+        ls -laFGh
+        du -shc *
+
+    # - name: Publish (push gh-pages branch) only on demand
+    #   uses: peaceiris/actions-gh-pages@v3
+    #   if: ${{ github.event.inputs.deploy }}
+    #   with:
+    #     publish_branch: gh-pages
+    #     github_token: ${{ secrets.GITHUB_TOKEN }}
+    #     publish_dir: ${{ env.TMP_DIR }}
+    #     force_orphan: true

CHANGES.rst

@@ -26,12 +26,13 @@ describe the future plans.
 1.6.10
 ******
 
-release expected by 2023-01-06
+release expected by 2023-01-13
 
 New Features
 ------------
 
 * Add ``apstools.utils.plotxy()`` utility function.
+* Add tag-based documentation selection via PyData switcher.
 
 Fixes
 ------------
@@ -41,6 +42,7 @@ Fixes
 Maintenance
 ------------
 
+* Pin Sphinx to `<6` due to problems with PyData and Sphinx v6.
 * Remove ``nsls2forge`` channel from conda environment.
 
 New Contributors

docs/source/_static/switcher.json

@@ -1,7 +1,20 @@
-[
-    {
-        "name": "development (main branch)",
-        "version": "dev",
-        "url": "https://bcda-aps.github.io/apstools/dev/"
-    }
-]
+[
+    {
+        "name": "development (main branch)",
+        "version": "dev",
+        "url": "https://bcda-aps.github.io/apstools/dev/"
+    },
+    {
+        "name": "1.6.9 (latest)",
+        "version": "1.6.9",
+        "url": "https://bcda-aps.github.io/apstools/1.6.9/"
+    },
+    {
+        "version": "1.6.8",
+        "url": "https://bcda-aps.github.io/apstools/1.6.8/"
+    },
+    {
+        "version": "1.6.6",
+        "url": "https://bcda-aps.github.io/apstools/1.6.6/"
+    }
+]

docs/source/conf.py

@@ -5,8 +5,8 @@
 
 # -- Path setup --------------------------------------------------------------
 
-from importlib.metadata import version
 import configparser
+import json
 import pathlib
 import sys
 
@@ -30,9 +30,25 @@
 # -- Special handling for version numbers ------------------------------------
 # https://github.com/pypa/setuptools_scm#usage-from-sphinx
 
-release = version(project)
+gh_org = "BCDA-APS"
+release = apstools.__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
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -57,10 +73,20 @@
 
 today_fmt = "%Y-%m-%d %H:%M"
 
-# html_theme = "alabaster"
-# html_theme = "furo"
-html_theme = "pydata_sphinx_theme"
+html_css_files = [
+    "css/custom.css",
+]
 html_static_path = ["_static"]
+html_theme = "pydata_sphinx_theme"
+# fmt: off
+html_theme_options = {
+    "navbar_start": ["navbar-logo", "version-switcher"],
+    "switcher": {
+        "json_url": switcher_json_url,
+        "version_match": release if release in switcher_version_list else "dev"
+    }
+}
+# fmt: on
 
 autodoc_mock_imports = """
     bluesky

docs/source/css/custom.css

@@ -0,0 +1,9 @@
+/* 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);
+ }

requirements-sphinx.txt

@@ -7,3 +7,4 @@ pydata-sphinx-theme
 pygments >=2.12
 pygments-ipython-console
 setuptools-scm
+sphinx <6