From 191e01ff61c16c7dae7594d271f7e5db22f9b80b Mon Sep 17 00:00:00 2001
From: scriptautomate-bc <204508229+scriptautomate-bc@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:26:46 -0500
Subject: [PATCH 1/2] Migrate to pydata Sphinx theme

---
 .devcontainer/Dockerfile          |   2 +-
 docs/_templates/globaltoc.html    | 104 ++++++++++++++++++++++++++++++
 docs/_templates/header-links.html |  81 +++++++++++++++++++++++
 docs/conf.py                      |  32 ++++-----
 docs/requirements.txt             |   2 +-
 5 files changed, 200 insertions(+), 21 deletions(-)
 create mode 100644 docs/_templates/globaltoc.html
 create mode 100644 docs/_templates/header-links.html

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index a7cd828..ae19143 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -1,4 +1,4 @@
-FROM bitnami/python:3.13
+FROM python:3.14
 
 RUN apt update && apt upgrade -y && apt install vim -y
 
diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html
new file mode 100644
index 0000000..7164405
--- /dev/null
+++ b/docs/_templates/globaltoc.html
@@ -0,0 +1,104 @@
+<h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
+<div id="salt-globaltoc">
+{{ toctree(includehidden=True, collapse=False, maxdepth=1) }}
+</div>
+
+<style>
+#salt-globaltoc {
+    font-size: 0.875rem;
+}
+
+#salt-globaltoc ul {
+    list-style: none;
+    padding: 0;
+    margin: 0 0 0.25rem 0;
+}
+
+#salt-globaltoc p.caption {
+    display: flex;
+    align-items: center;
+    gap: 0.4em;
+    cursor: pointer;
+    font-size: 0.75rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--pst-color-text-muted, #6c757d);
+    padding: 0.35rem 0.25rem 0.35rem 0;
+    margin: 0.75rem 0 0 0;
+    user-select: none;
+}
+
+#salt-globaltoc p.caption:hover {
+    color: var(--pst-color-text-base, inherit);
+}
+
+/* Triangle arrow indicator */
+#salt-globaltoc p.caption::before {
+    content: "";
+    display: inline-block;
+    flex-shrink: 0;
+    width: 0;
+    height: 0;
+    border-style: solid;
+    border-width: 4px 0 4px 6px;
+    border-color: transparent transparent transparent currentColor;
+    transition: transform 0.15s ease;
+}
+
+#salt-globaltoc p.caption.expanded::before {
+    transform: rotate(90deg);
+}
+
+#salt-globaltoc .toctree-l1 > a {
+    display: block;
+    padding: 0.25rem 0.5rem;
+    color: var(--pst-color-text-base, inherit);
+    text-decoration: none;
+    border-radius: 4px;
+    line-height: 1.4;
+}
+
+#salt-globaltoc .toctree-l1 > a:hover {
+    background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.06));
+}
+
+#salt-globaltoc .toctree-l1.current > a,
+#salt-globaltoc .toctree-l1.current > a:hover {
+    font-weight: 600;
+    background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.06));
+    color: var(--pst-color-primary, #0099cd);
+}
+</style>
+
+<script>
+(function () {
+    function initCollapsible() {
+        var container = document.getElementById("salt-globaltoc");
+        if (!container) return;
+
+        container.querySelectorAll("p.caption").forEach(function (caption) {
+            var ul = caption.nextElementSibling;
+            if (!ul || ul.tagName !== "UL") return;
+
+            if (ul.querySelector("li.current")) {
+                caption.classList.add("expanded");
+            } else {
+                ul.style.display = "none";
+            }
+
+            caption.addEventListener("click", function () {
+                var isCollapsed = ul.style.display === "none";
+                ul.style.display = isCollapsed ? "" : "none";
+                caption.classList.toggle("expanded", isCollapsed);
+            });
+        });
+    }
+
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", initCollapsible);
+    } else {
+        initCollapsible();
+    }
+})();
+</script>
diff --git a/docs/_templates/header-links.html b/docs/_templates/header-links.html
new file mode 100644
index 0000000..87caf05
--- /dev/null
+++ b/docs/_templates/header-links.html
@@ -0,0 +1,81 @@
+<style>
+  /* Styling for our custom links in the header center */
+  .bd-header .navbar-nav {
+    flex-direction: row !important;
+    align-items: center !important;
+  }
+
+  .bd-header .navbar-nav li.nav-item.custom-nav-item {
+    margin: 0 0.75rem;
+  }
+
+  .bd-header .navbar-nav li.nav-item.custom-nav-item a.nav-link {
+    color: var(--color-foreground-secondary);
+    text-decoration: none;
+    font-weight: 500;
+    font-size: 0.9rem;
+    white-space: nowrap;
+    padding: 0.5rem 0;
+    transition: color 0.2s;
+  }
+
+  .bd-header .navbar-nav li.nav-item.custom-nav-item a.nav-link:hover {
+    color: var(--color-foreground-primary);
+  }
+
+  .bd-header .navbar-nav li.nav-item.custom-nav-item.active a.nav-link {
+    font-weight: 700;
+    color: var(--pst-color-primary, var(--color-brand-primary, #0099cd));
+  }
+
+  /* Style the globaltoc sidebar to look like PyData theme */
+  .sidebar-primary-item .toctree-l1 {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+  .sidebar-primary-item .toctree-l1 > a {
+    display: block;
+    padding: 0.5rem 1rem;
+    color: var(--color-foreground-secondary);
+    text-decoration: none;
+    font-size: 0.9rem;
+    border-radius: 4px;
+  }
+  .sidebar-primary-item .toctree-l1 > a:hover {
+    background-color: var(--color-sidebar-item-background--hover);
+    color: var(--color-foreground-primary);
+  }
+  .sidebar-primary-item .toctree-l1.current > a {
+    font-weight: 600;
+    color: var(--color-brand-primary);
+  }
+  .sidebar-primary-item ul {
+    padding-left: 1.5rem;
+    list-style: none;
+  }
+</style>
+
+<!-- This template injects cross-doc navigation links into the navbar center -->
+<script>
+  document.addEventListener("DOMContentLoaded", function() {
+    const navbarCenter = document.querySelector(".navbar-header-items__center .navbar-nav");
+    if (navbarCenter) {
+      // Clear any existing (internal) links we don't want
+      navbarCenter.innerHTML = "";
+
+      const links = [
+        { name: "Install Guide", url: "https://docs.saltproject.io/salt/install-guide/en/latest/", active: true },
+        { name: "User Guide", url: "https://docs.saltproject.io/salt/user-guide/en/latest/" },
+        { name: "Reference Docs", url: "https://docs.saltproject.io/en/latest/contents.html" }
+      ];
+
+      links.forEach(link => {
+        const li = document.createElement("li");
+        li.className = "nav-item custom-nav-item" + (link.active ? " active" : "");
+        li.innerHTML = `<a class="nav-link" href="${link.url}">${link.name}</a>`;
+        navbarCenter.appendChild(li);
+      });
+    }
+  });
+</script>
diff --git a/docs/conf.py b/docs/conf.py
index 5ba4862..d254bd8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -118,7 +118,7 @@ def setup(app):
 source_suffix = {".rst": "restructuredtext"}
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ["_templates"]
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -138,11 +138,9 @@ def setup(app):
 # a list of builtin themes.
 #
 
-# Base Furo Theme requirements
-# More: https://pradyunsg.me/furo/customisation/
 html_show_sourcelink = True  # False on private repos; True on public repos
-html_theme = "furo"
-html_title = "Salt install guide"
+html_theme = 'pydata_sphinx_theme'
+html_title = project
 html_baseurl = "https://docs.saltproject.io/salt/install-guide/"
 
 # Extends baseurl, in combination with version value
@@ -153,14 +151,20 @@ def setup(app):
     "genindex.html",
 ]
 
+html_logo = None
 html_theme_options = {
-    "dark_css_variables": {
-        "color-brand-primary": "#66CCF4",
-        "color-brand-content": "#66CCF4",
+    "logo": {
+        "image_light": "_static/img/SaltProject_altlogo_blue.png",
+        "image_dark": "_static/img/SaltProject_altlogo_blue.png",
     },
-    # "announcement": '<font color="orange"><strong>IMPORTANT ANNOUNCEMENT:</strong> repo.saltproject.io has migrated to packages.broadcom.com!<br /><strong><a href="https://saltproject.io/blog/post-migration-salt-project-faqs/" target="_blank" rel="noopener noreferrer">Click here for migration FAQs (2024-11-22)</a></strong></font>',
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav", "header-links"],
+    "navbar_end": ["theme-switcher", "navbar-icon-links"],
+    "navigation_depth": 4,
 }
 
+html_sidebars = {"**": ["globaltoc.html"]}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -176,16 +180,6 @@ def setup(app):
 
 copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre"
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-# For example, official Salt Project docs use images from the salt-branding-guide
-# https://gitlab.com/saltstack/open/salt-branding-guide/
-#
-# Example for >=4.0.0 of Sphinx (support for favicon via URL)
-# html_logo = "https://gitlab.com/saltstack/open/salt-branding-guide/-/raw/master/logos/SaltProject_altlogo_teal.png"
-# Example for <4.0.0 of Sphinx, if added into _static/img/ and html_static_path is valid
-html_logo = "_static/img/SaltProject_altlogo_blue.png"
-
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large. Favicons can be up to at least 228x228. PNG
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 0351271..b0d2b2f 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,4 @@
-furo>=2024.8.6
+pydata-sphinx-theme>=0.18.0
 sphinx-copybutton>=0.5.2
 sphinx-design>=0.5.0
 sphinx-inline-tabs>=2023.4.21

From 62f107ac06f96e80b57894611f5b940b6af29bfd Mon Sep 17 00:00:00 2001
From: scriptautomate-bc <204508229+scriptautomate-bc@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:43:11 -0500
Subject: [PATCH 2/2] Expandable left-hand nav TOC based on subpages

---
 docs/_templates/globaltoc.html | 134 ++++++++++++++++++++++++++++++---
 docs/conf.py                   |   2 +-
 2 files changed, 124 insertions(+), 12 deletions(-)

diff --git a/docs/_templates/globaltoc.html b/docs/_templates/globaltoc.html
index 7164405..1b136d2 100644
--- a/docs/_templates/globaltoc.html
+++ b/docs/_templates/globaltoc.html
@@ -1,6 +1,6 @@
 <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
 <div id="salt-globaltoc">
-{{ toctree(includehidden=True, collapse=False, maxdepth=1) }}
+{{ toctree(includehidden=True, collapse=False, maxdepth=2) }}
 </div>
 
 <style>
@@ -14,6 +14,13 @@ <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
     margin: 0 0 0.25rem 0;
 }
 
+/* Indent nested levels */
+#salt-globaltoc ul ul {
+    padding-left: 0.75rem;
+    margin: 0;
+    width: 100%;
+}
+
 #salt-globaltoc p.caption {
     display: flex;
     align-items: center;
@@ -33,7 +40,7 @@ <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
     color: var(--pst-color-text-base, inherit);
 }
 
-/* Triangle arrow indicator */
+/* Triangle arrow indicator on captions */
 #salt-globaltoc p.caption::before {
     content: "";
     display: inline-block;
@@ -50,7 +57,56 @@ <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
     transform: rotate(90deg);
 }
 
-#salt-globaltoc .toctree-l1 > a {
+/* Flex layout for li items that have children, so link + toggle button sit on one row */
+#salt-globaltoc li.has-children {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+}
+
+#salt-globaltoc li.has-children > a {
+    flex: 1;
+    min-width: 0;
+}
+
+#salt-globaltoc li.has-children > ul {
+    width: 100%;
+}
+
+/* Toggle button injected next to links that have children */
+#salt-globaltoc .toc-toggle {
+    flex-shrink: 0;
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 0.25rem 0.35rem;
+    color: var(--pst-color-text-muted, #6c757d);
+    line-height: 1;
+    border-radius: 4px;
+}
+
+#salt-globaltoc .toc-toggle:hover {
+    color: var(--pst-color-text-base, inherit);
+    background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.06));
+}
+
+#salt-globaltoc .toc-toggle::before {
+    content: "";
+    display: inline-block;
+    width: 0;
+    height: 0;
+    border-style: solid;
+    border-width: 4px 0 4px 6px;
+    border-color: transparent transparent transparent currentColor;
+    transition: transform 0.15s ease;
+}
+
+#salt-globaltoc .toc-toggle.expanded::before {
+    transform: rotate(90deg);
+}
+
+/* Link styles for all toctree levels */
+#salt-globaltoc li > a {
     display: block;
     padding: 0.25rem 0.5rem;
     color: var(--pst-color-text-base, inherit);
@@ -59,33 +115,42 @@ <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
     line-height: 1.4;
 }
 
-#salt-globaltoc .toctree-l1 > a:hover {
+#salt-globaltoc li > a:hover {
     background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.06));
 }
 
-#salt-globaltoc .toctree-l1.current > a,
-#salt-globaltoc .toctree-l1.current > a:hover {
+#salt-globaltoc li.current > a,
+#salt-globaltoc li.current > a:hover {
     font-weight: 600;
     background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.06));
     color: var(--pst-color-primary, #0099cd);
 }
+
+/* Slightly smaller text for deeper levels */
+#salt-globaltoc .toctree-l2 > a,
+#salt-globaltoc .toctree-l3 > a,
+#salt-globaltoc .toctree-l4 > a {
+    font-size: 0.85rem;
+    padding: 0.18rem 0.5rem;
+}
 </style>
 
 <script>
 (function () {
+    function hasCurrentDescendant(ul) {
+        return !!ul.querySelector("li.current");
+    }
+
     function initCollapsible() {
         var container = document.getElementById("salt-globaltoc");
         if (!container) return;
 
+        // Caption-level collapsing (start expanded by default)
         container.querySelectorAll("p.caption").forEach(function (caption) {
             var ul = caption.nextElementSibling;
             if (!ul || ul.tagName !== "UL") return;
 
-            if (ul.querySelector("li.current")) {
-                caption.classList.add("expanded");
-            } else {
-                ul.style.display = "none";
-            }
+            caption.classList.add("expanded");
 
             caption.addEventListener("click", function () {
                 var isCollapsed = ul.style.display === "none";
@@ -93,6 +158,53 @@ <h3><a href="{{ pathto(root_doc)|e }}">{{ project|title }}</a></h3>
                 caption.classList.toggle("expanded", isCollapsed);
             });
         });
+
+        // Nested li collapsing: any li that directly contains a ul
+        container.querySelectorAll("li").forEach(function (li) {
+            var childUl = li.querySelector(":scope > ul");
+            if (!childUl) return;
+
+            var link = li.querySelector(":scope > a");
+            if (!link) return;
+
+            // Distinguish sub-pages (no # in href) from intra-page section headers (# in href)
+            var childLinks = childUl.querySelectorAll(":scope > li > a");
+            var hasSubPages = false;
+            childLinks.forEach(function (childLink) {
+                var href = childLink.getAttribute("href") || "";
+                if (href.indexOf("#") === -1) {
+                    hasSubPages = true;
+                }
+            });
+
+            if (!hasSubPages) {
+                // Children are section headers of this page — hide them entirely
+                childUl.style.display = "none";
+                return;
+            }
+
+            li.classList.add("has-children");
+
+            var btn = document.createElement("button");
+            btn.className = "toc-toggle";
+            btn.setAttribute("aria-label", "Toggle section");
+
+            var expanded = li.classList.contains("current") || hasCurrentDescendant(childUl);
+            if (expanded) {
+                btn.classList.add("expanded");
+            } else {
+                childUl.style.display = "none";
+            }
+
+            link.insertAdjacentElement("afterend", btn);
+
+            btn.addEventListener("click", function (e) {
+                e.stopPropagation();
+                var isCollapsed = childUl.style.display === "none";
+                childUl.style.display = isCollapsed ? "" : "none";
+                btn.classList.toggle("expanded", isCollapsed);
+            });
+        });
     }
 
     if (document.readyState === "loading") {
diff --git a/docs/conf.py b/docs/conf.py
index d254bd8..de74e71 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -139,7 +139,7 @@ def setup(app):
 #
 
 html_show_sourcelink = True  # False on private repos; True on public repos
-html_theme = 'pydata_sphinx_theme'
+html_theme = "pydata_sphinx_theme"
 html_title = project
 html_baseurl = "https://docs.saltproject.io/salt/install-guide/"