Enable version warning banners for docs (#7139)

* Enable version warning banners for docs

If the doc version isn't the preferred one, a warning banner is shown
at the top. This also accounts for dev builds.

* Update PyData theme to fixed 0.14.1

0.14.1 fixes a broken version comparison in the javascript of the
version warning banner. See
pydata/pydata-sphinx-theme#1446 for more.

* Revert to proper version_switcher.json URL

RELEASE.txt

@@ -82,8 +82,8 @@ the appropriate point in main and the following instructions are still apt.
   Once everything works as intended, remove those branches and proceed.
 
 - Edit ``doc/source/_static/docversions.js`` and
-  ``doc/source/_static/version_switcher.json`` in order to
-  add the release, e.g., `0.15.x`, and commit.
+  ``doc/source/_static/version_switcher.json`` in order to add the release, move the
+  key value pair `"preferred": true` to the most recent stable version, and commit.
 
 - Update the version number to stable in ``skimage/__init__.py``, and commit.
 

doc/source/_static/version_switcher.json

@@ -7,7 +7,8 @@
     {
         "name": "0.21 (stable)",
         "version":"0.21.0",
-        "url": "https://scikit-image.org/docs/stable/"
+        "url": "https://scikit-image.org/docs/stable/",
+        "preferred": true
     },
     {
         "name": "0.20",

doc/source/conf.py

@@ -155,19 +155,27 @@
     },
     "header_links_before_dropdown": 6,
     "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/scikit-image/scikit-image",
+            "icon": "fa-brands fa-github",
+        },
         {
             "name": "PyPI",
             "url": "https://pypi.org/project/scikit-image/",
             "icon": "fa-solid fa-box",
         },
     ],
+    "navbar_align": "left",
     "navbar_end": ["version-switcher", "navbar-icon-links"],
     "show_prev_next": False,
     "switcher": {
-        "json_url": "https://scikit-image.org/docs/dev/_static/version_switcher.json",
+        "json_url": (
+            "https://scikit-image.org/docs/dev/_static/version_switcher.json"
+        ),
         "version_match": "dev" if "dev" in version else version,
     },
-    "github_url": "https://github.com/scikit-image/scikit-image",
+    "show_version_warning_banner": True,
     # Footer
     "footer_start": ["copyright"],
     "footer_end": ["sphinx-version", "theme-version"],

pyproject.toml

@@ -82,7 +82,7 @@ docs = [
     'kaleido',
     'scikit-learn>=1.1',
     'sphinx_design>=0.3',
-    'pydata-sphinx-theme>=0.13',
+    'pydata-sphinx-theme>=0.14.1',
 ]
 optional = [
     'SimpleITK',

requirements/docs.txt

@@ -18,4 +18,4 @@ plotly>=5.10
 kaleido
 scikit-learn>=1.1
 sphinx_design>=0.3
-pydata-sphinx-theme>=0.13
+pydata-sphinx-theme>=0.14.1