Use dataclasses instead of extra_classes (#597)

* Use dataclasses instead of extra_classes

* Fix CSS

* Uncomment proper json

* Fix docs'

* Fix up the CSS of the dropdown

* Docs update

Author: choldgraf

docs/_static/custom.css

@@ -0,0 +1,16 @@
+/* Background of stsable should be green */
+#version_switcher a[data-version-name*="stable"] {
+  background-color: #e2ffe2;
+}
+
+/* Color of explicit versions should be orange */
+#version_switcher
+  a:not([data-version-name*="stable"]):not([data-version-name="dev"]) {
+  background-color: #f8f9fa;
+  color: grey;
+}
+
+/* If we're on a dev version, make the switcher button orange */
+#version_switcher_button[data-active-version-name*="dev"] {
+  background-color: rgb(255 138 62);
+}

docs/_static/switcher.json

@@ -1,8 +1,7 @@
 [
   {
     "name": "dev",
-    "version": "latest",
-    "extra_classes": ["dev"]
+    "version": "latest"
   },
   {
     "name": "0.8.0 (stable)",

docs/conf.py

@@ -145,6 +145,7 @@
     "demo/no-sidebar": [],  # Test what page looks like with no sidebar items
 }
 
+myst_heading_anchors = 2
 
 html_context = {
     "github_user": "pandas-dev",
@@ -161,3 +162,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+
+def setup(app):
+    app.add_css_file("custom.css")

docs/user_guide/configuring.rst

@@ -386,9 +386,6 @@ each can have the following fields:
   switcher.
 - ``name``: an optional name to display in the switcher dropdown instead of the
   version string (e.g., "latest", "stable", "dev", etc).
-- ``extra_classes``: an optional list of classes to add to the switcher
-  button for a given version (e.g., ``["dev", "rc"]``). These classes are only
-  added when the version is active.
 - ``url``: an optional URL. If provided, it links the version to ``url``
   instead of ``switcher['url_template']``.
 
@@ -403,7 +400,6 @@ Here is an example JSON file:
         },
         {
             "version": "2.1rc1",
-            "extra_classes": ["dev", "rc"]
         },
         {
             "version": "2.0"
@@ -542,6 +538,57 @@ to insert a version switcher at the top of the left sidebar, while still
 keeping the default navigation below it. See :doc:`sections` for more
 information.
 
+Style the switcher buttons
+--------------------------
+
+You may apply styles via CSS to any of the switcher buttons to control their look and feel.
+Each button has two `HTML dataset entries <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset>`_
+that you can use to apply CSS rules to subsets of buttons. These entries are:
+
+.. code-block::
+
+   data-version
+   data-version-name
+
+For example, the link for an entry with ``version="0.2"``,
+and ``name="My version"`` would have metadata like so:
+
+.. code-block:: html
+
+   <a data-version-name="My version" data-version="0.2" class="<classes...>">
+
+You can create CSS rules that select this metadata like so:
+
+.. code-block:: scss
+
+   // Style all links with a specific subset of versions
+   #version_switcher a[data-version="0.2"],
+   #version_switcher a[data-version="0.3"] {
+      background-color: red;
+   }
+   // Style all links with `stable` in the version name
+   #version_switcher a[data-version-name*="stable"] {
+      background-color: green;
+   }
+
+In addition, the parent button of the dropdown list contains similar metadata
+about the **current version**. This could be used to style the entire dropdown
+a certain color based on the active version.
+
+For example, if you wanted to style the dropdown button orange if it was a ``dev``
+version, you could use the following CSS selector:
+
+.. code-block:: scss
+
+   // If the active version has the name "dev", style it orange
+   #version_switcher_button[data-active-version-name*="dev"] {
+      background-color: rgb(255 138 62);
+   }
+
+.. seealso::
+
+   See the `MDN documentation on dataset properties <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset>`_
+   for more information on using and styling with these properties.
 
 Add an Edit this Page button
 ============================

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html

@@ -66,18 +66,21 @@
             // trying to redirect, and if not, will redirect to the homepage
             // for that version of the docs.
             node.onclick = checkPageExistsAndRedirect;
+            // Add dataset values for the version and name in case people want
+            // to apply CSS styling based on this information.
+            node.dataset["versionName"] = entry.name;
+            node.dataset["version"] = entry.version;
+
             $("#version_switcher_menu").append(node);
             // replace dropdown button text with the preferred display name of
             // this version, rather than using sphinx's {{ version }} variable.
             // also highlight the dropdown entry for the currently-viewed
             // version's entry
             if (entry.version == "{{ theme_switcher.get('version_match') }}") {
                 node.classList.add("active");
-                $("#version_switcher_button").text(entry.name);
-                // Add extra class to the button for the selected entry
-                if ("extra_classes" in entry) {
-                    $("#version_switcher_menu")[0].classList.add(...entry.extra_classes);
-                }
+                let btn = document.getElementById("version_switcher_button");
+                btn.innerText = btn.dataset["activeVersionName"] = entry.name;
+                btn.dataset["activeVersion"] = entry.version;
             }
         });
     });