Move to pydata theme for unification

.devcontainer/Dockerfile

@@ -1,6 +1,6 @@
-FROM bitnami/python:3.13
+FROM python:3.14
 
-RUN apt update && apt upgrade -y && apt install vim -y
+RUN apt-get update && apt-get upgrade -y && apt-get install vim -y
 
 # Add dev requirements
 ADD requirements.txt /tmp/

README.rst

@@ -20,7 +20,7 @@ Salt User Guide
 If you're looking to learn about Salt, you've come to the right place.
 
 - `View the Sphinx-built documentation here <https://docs.saltproject.io/salt/user-guide/en/latest/index.html>`__
-- `View the source repo here <https://gitlab.com/saltstack/open/docs/salt-user-guide>`__
+- `View the source repo here <https://github.com/saltstack/salt-user-guide>`__
 
 About the Salt User Guide
 =========================

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>

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/" },
+        { name: "User Guide", url: "https://docs.saltproject.io/salt/user-guide/en/latest/", active: true },
+        { 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>

docs/conf.py

@@ -122,9 +122,8 @@ def setup(app):
 # a list of builtin themes.
 #
 
-# Base Material Theme requirements
 html_show_sourcelink = True  # False on private repos; True on public repos
-html_theme = 'furo'
+html_theme = 'pydata_sphinx_theme'
 html_title = project
 html_baseurl = 'https://docs.saltproject.io/salt/user-guide/'
 
@@ -136,13 +135,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_teal.png",
+        "image_dark": "_static/img/SaltProject_altlogo_teal.png",
     },
+    "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".
@@ -155,10 +161,6 @@ def setup(app):
     'css/local-testing.css'
 ]
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-html_logo = "_static/img/SaltProject_altlogo_teal.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

docs/index.rst

@@ -39,6 +39,6 @@ Table of Contents
    :caption: Contribute
 
    topics/list-of-images
-   See a problem? Open an issue! <https://gitlab.com/saltstack/open/docs/salt-user-guide/-/issues>
+   See a problem? Open an issue! <https://github.com/saltstack/salt-user-guide/issues>
    Salt docs contributing guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html>
    GitLab repository <https://gitlab.com/saltstack/open/docs/salt-user-guide>

docs/requirements.txt

@@ -1,5 +1,5 @@
 Sphinx-Substitution-Extensions>=2022.2.16
-furo>=2022.12.7
+pydata-sphinx-theme
 sphinx-copybutton>=0.5.1
 sphinx-design>=0.3.0
 sphinx-inline-tabs>=2022.1.2b11