Add sidebar version switcher for stable and dev documentation

Change-Id: I88038a020b1167b91131b6262f991e29d277751c

.github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 9d505ba..72a8c49 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -40,14 +40,19 @@
           git archive "${STABLE_TAG}" | tar -x -C "${RUNNER_TEMP}/stable-src"
           cp docs/source/conf.py docs/source/CNAME "${RUNNER_TEMP}/stable-src/docs/source/"
           rm -rf "${RUNNER_TEMP}/stable-src/docs/source/_templates"
+          cp -r docs/source/_templates "${RUNNER_TEMP}/stable-src/docs/source/_templates"
           sphinx-build -D nitpicky=0 \
-            -D "html_theme_options.announcement=Viewing documentation for the latest stable release (${STABLE_TAG}). For unreleased features on master, see the <a href=\"/dev/\">development documentation</a>." \
+            -A ceres_doc_variant=stable \
+            -A "stable_version=${STABLE_TAG}" \
+            -D "html_theme_options.source_branch=${STABLE_TAG}" \
             -b html "${RUNNER_TEMP}/stable-src/docs/source" _site
 
       - name: Build development (HEAD) documentation
         run: |
+          STABLE_TAG=$(git tag --list '[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -n1)
           sphinx-build -W -n \
-            -D 'html_theme_options.announcement=Viewing development documentation for the master branch. For the latest stable release, see the <a href="/">stable documentation</a>.' \
+            -A ceres_doc_variant=dev \
+            -A "stable_version=${STABLE_TAG}" \
             -b html docs/source _site/dev
 
       - name: Upload Pages artifact

docs/source/_templates/sidebar/brand.html

diff --git a/docs/source/_templates/sidebar/brand.html b/docs/source/_templates/sidebar/brand.html
new file mode 100644
index 0000000..0ad683c
--- /dev/null
+++ b/docs/source/_templates/sidebar/brand.html
@@ -0,0 +1,58 @@
+{% include "!sidebar/brand.html" %}
+{%- set is_stable = (ceres_doc_variant == 'stable') -%}
+{%- set target_file = (pagename if pagename else master_doc) + (file_suffix if file_suffix else '.html') -%}
+{%- set stable_href = pathto(target_file, 1) if is_stable else pathto('../' + target_file, 1) -%}
+{%- set dev_href = pathto('dev/' + target_file, 1) if is_stable else pathto(target_file, 1) -%}
+<style>
+  .sidebar-version-switch {
+    padding: 0 var(--sidebar-item-spacing-horizontal) var(--sidebar-item-spacing-vertical);
+  }
+  .sidebar-version-pills {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 2px;
+    padding: 3px;
+    border-radius: 6px;
+    background: var(--color-background-hover);
+    border: 1px solid var(--color-background-border);
+  }
+  .sidebar-version-pill {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0.3rem 0.4rem;
+    border-radius: 4px;
+    font-size: var(--font-size--small--3);
+    font-weight: 500;
+    line-height: 1.2;
+    color: var(--color-foreground-secondary);
+    text-decoration: none;
+    white-space: nowrap;
+    transition: background-color 0.15s ease, color 0.15s ease;
+  }
+  .sidebar-version-pill:hover {
+    color: var(--color-foreground-primary);
+    background: var(--color-background-primary);
+    text-decoration: none;
+  }
+  .sidebar-version-pill.is-active,
+  .sidebar-version-pill.is-active:hover {
+    background: var(--color-brand-primary);
+    color: #ffffff;
+    font-weight: 600;
+  }
+</style>
+<div class="sidebar-version-switch" role="navigation" aria-label="Documentation version">
+  <div class="sidebar-version-pills">
+    <a class="sidebar-version-pill{% if is_stable %} is-active{% endif %}"
+       href="{{ stable_href }}"
+       {% if is_stable %}aria-current="page"{% endif %}>
+      Stable ({{ stable_version }})
+    </a>
+    <a class="sidebar-version-pill{% if not is_stable %} is-active{% endif %}"
+       href="{{ dev_href }}"
+       {% if not is_stable %}aria-current="page"{% endif %}>
+      Dev (master)
+    </a>
+  </div>
+</div>

docs/source/conf.py

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 9ff3880..dd1352f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -55,6 +55,7 @@
 if importlib.util.find_spec('sphinx_copybutton') is not None:
     extensions.append('sphinx_copybutton')
 
+templates_path = ['_templates']
 master_doc = 'index'
 exclude_patterns = []
 nitpicky = True
@@ -91,6 +92,10 @@
     'source_branch': 'master',
     'source_directory': 'docs/source/',
 }
+html_context = {
+    'ceres_doc_variant': 'dev',
+    'stable_version': _stable_version,
+}
 html_extra_path = ['CNAME']
 html_domain_indices = True
 html_use_index = True