CI - Fix three separate test failures (a11y, Sphinx dev, Sphinx 7.3) (#2204)

gabalafou · web-flow · commit 441c98d64bee · 2025-05-12T11:17:24.000+01:00
Fixes #2199. This should also: - fix the a11y-tests CI check which is currently failing on all new PRs - fix a warning that occurs whenever Sphinx >= 7.3 is used - fix a warning that occurs when the latest/dev version of Sphinx is used ### How to test Run a contrast checker on the following preview build pages. Check each page both in **light mode** and **dark mode**: 1. [Read the Docs - PR 2204 - Kitchen Sink - Tables](https://pydata-sphinx-theme--2204.org.readthedocs.build/en/2204/examples/kitchen-sink/tables.html) - specifically check "list tables" 2. [Read the Docs - PR 2204 - Kitchen Sink - Admonitions](https://pydata-sphinx-theme--2204.org.readthedocs.build/en/2204/examples/kitchen-sink/admonitions.html) - specifically check the following five admonitions: topic, version added, version changed, deprecated and version removed ### Screenshots The following two screenshots, one for light mode and one for dark mode, show the topic admonition (with higher contrast link) above a regular admonition to show the difference between the regular contrast link color versus the higher contrast link color. <img width="746" alt="light mode topic admonition shown next to normal admonition" src="https://github.com/user-attachments/assets/6725331f-c107-4345-a056-e21e395353f2" /> <img width="746" alt="dark mode topic admonition shown next to normal admonition" src="https://github.com/user-attachments/assets/9b4def23-5d68-4dc9-af10-47ad362f431e" /> <br/> <br/> The following two screenshots, one for light mode and one for dark mode, show the four different version-related admonitions, which use higher contrast links, below a warning admonition, which uses regular contrast. <img width="746" alt="five light mode admonitions shown together, four of which have higher contrast links" src="https://github.com/user-attachments/assets/7ab7e1d2-cc05-4b23-a1bb-132eb2aa253f" /> <br/> <br/> Note that in the version changed admonition (dark mode), the link color is even higher contrast (teal-300) than the other higher contrast links (teal-400). <img width="746" alt="five dark mode admonitions shown together, four of which have higher contrast links" src="https://github.com/user-attachments/assets/9941ead6-b038-4de0-b8c8-f92f716bd08c" /> <br/> <br/> The following two screenshots show the same table in light and dark mode (all of the links use the higher contrast color). <img width="746" alt="light mode table with links" src="https://github.com/user-attachments/assets/22b087fe-facc-4cff-8fe9-6558edff29a8" /> <img width="746" alt="dark mode table with links" src="https://github.com/user-attachments/assets/8796cda5-ebd9-4769-a689-03c2e3bd5870" />
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -101,10 +101,8 @@ jobs:
           # ensuring proper scaping of the variable
           docs_dir="${DOCS_DIR}"
           mkdir -p $docs_dir/site
-          cp -r docs/examples/kitchen-sink $docs_dir/site/kitchen-sink
-          printf "Test\n====\n\n.. toctree::\n\n   kitchen-sink/index\n" > $docs_dir/site/index.rst
+          cp -r docs/examples/kitchen-sink/* $docs_dir/site/
           echo 'html_theme = "pydata_sphinx_theme"' > $docs_dir/site/conf.py
-          echo '.. toctree::\n   :glob:\n\n   *' >> $docs_dir/site/index.rst
 
           # build docs without checking for warnings
           python -Im tox run -e docs-no-checks
diff --git a/.github/workflows/lighthouserc.json b/.github/workflows/lighthouserc.json
@@ -1,7 +1,12 @@
 {
   "ci": {
     "collect": {
-      "staticDistDir": "./audit/_build/kitchen-sink/",
+      "staticDistDir": "./audit/_build/",
+      "autodiscoverUrlBlocklist": [
+        "/genindex.html",
+        "/search.html",
+        "/_static/webpack-macros.html"
+      ],
       "settings": {
         "skipAudits": ["canonical"]
       }
diff --git a/docs/community/inspiration.md b/docs/community/inspiration.md
@@ -20,7 +20,7 @@ When making new decisions about design and UI/UX, we often consult these themes
   image: ../_static/inspiration/docker-mark-blue.svg
 - title: "**PyTorch**"
   link: https://pytorch.org/docs/stable/index.html
-  image: https://pytorch.org/assets/images/pytorch-logo.png
+  image: https://docs.pytorch.org/docs/stable/_static/images/logo-dark.svg
 - title: "**Docasaurus**"
   link: https://docusaurus.io/docs
   image: https://d33wubrfki0l68.cloudfront.net/c088b7acfcf11100903c44fe44f2f2d7e0f30531/47727/img/docusaurus.svg
diff --git a/docs/conf.py b/docs/conf.py
@@ -369,8 +369,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     # The crawler gets "Anchor not found" for various anchors
     r"https://github.com.+?#.*",
     r"https://www.sphinx-doc.org/en/master/*/.+?#.+?",
-    # Known broken links in kitchen sink
-    r"https://source.unsplash.com/.+",
     # sample urls
     "http://someurl/release-0.1.0.tar-gz",
     "http://python.py",
diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -26,6 +26,13 @@
   color: var(--pst-color-table);
   border: 1px solid var(--pst-color-table-outer-border);
 
+  // Our tables are zebra striped: header rows and odd-numbered rows have an
+  // off-white background, or off-black in dark mode. So they require a
+  // higher contrast link color.
+  a {
+    color: var(--pst-color-link-higher-contrast);
+  }
+
   th,
   td {
     ~ th,
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
@@ -23,6 +23,11 @@ div.versionremoved {
     margin-bottom: 0.6rem;
     margin-top: 0.6rem;
   }
+
+  // fix color contrast failures (accessibility)
+  a {
+    color: var(--pst-color-link-higher-contrast);
+  }
 }
 
 div.versionadded {
@@ -33,6 +38,14 @@ div.versionadded {
 div.versionchanged {
   border-color: var(--pst-color-warning);
   background-color: var(--pst-color-warning-bg);
+
+  html[data-theme="dark"] & {
+    // This is a one-off because `--pst-color-link-higher-contrast` works for
+    // all of the other admonitions except this one in dark mode.
+    a {
+      color: map-deep-get($color-palette, "teal", "300");
+    }
+  }
 }
 
 div.deprecated,
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -300,6 +300,10 @@ aside.topic {
     color: var(--pst-color-on-surface) !important;
   }
 
+  a {
+    color: var(--pst-color-link-higher-contrast);
+  }
+
   // Over-ride large default padding
   ul.simple {
     padding-left: 1rem;
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -58,7 +58,7 @@ code.literal {
 }
 
 a > code {
-  color: var(--pst-color-inline-code-links);
+  color: var(--pst-color-link-higher-contrast);
 
   &:hover {
     color: var(--pst-color-link-hover);
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
@@ -26,7 +26,7 @@ blockquote {
 
   // Ensure there is enough contrast against the background
   a {
-    color: var(--pst-color-inline-code-links);
+    color: var(--pst-color-link-higher-contrast);
   }
 
   // hack to make the text in the blockquote selectable
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
@@ -36,7 +36,7 @@
 
   // Ensure there is enough contrast against the background
   a {
-    color: var(--pst-color-inline-code-links);
+    color: var(--pst-color-link-higher-contrast);
   }
 
   // The "Switch to stable version" link (styled like a button)
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -199,10 +199,12 @@ $pst-semantic-colors: (
     "light": #{map-deep-get($color-palette, "pink", "600")},
     "dark": #{map-deep-get($color-palette, "pink", "300")},
   ),
-  "inline-code-links": (
-    // need to make sure there is enough contrast against the code bg
+  "link-higher-contrast": (
+    // teal-600 provides higher contrast than teal-500 (our regular light mode
+    // link color) for off-white or non-white backgrounds
     "light": #{map-deep-get($color-palette, "teal", "600")},
-    // keep primary color for dark mode
+    // teal-400 is actually the same color already used for links in dark mode,
+    // but it actually works for most of our other dark mode backgrounds
     "dark": #{map-deep-get($color-palette, "teal", "400")},
   ),
   "target": (
diff --git a/tests/intermittent_warning_list.txt b/tests/intermittent_warning_list.txt
@@ -2,7 +2,8 @@ WARNING: Cell printed to stderr:
 Matplotlib is building the font cache; this may take a moment.
 WARNING: failed to reach any of the inventories with the following issues:
 intersphinx inventory
-# THESE 3 WILL GO AWAY WHEN OUR MIN SPHINX VERSION IS 7.3 OR HIGHER
+# THE FOLLOWING 4 LINES WILL GO AWAY WHEN OUR MIN SPHINX VERSION IS 7.3 OR HIGHER (because 7.3 introduces the versionremoved directive)
+We also support *italic*, **bold**, ``code``, `links <https://www.sphinx-doc.org/en/master/>`_, and more.
 Here's a version removed message.
 .. versionremoved:: v0.1.1
 ERROR: Unknown directive type "versionremoved".
diff --git a/tests/sites/base/conf.py b/tests/sites/base/conf.py
@@ -21,3 +21,6 @@
 
 # Base options, we can add other key/vals later
 html_sidebars = {"section1/index": ["sidebar-nav-bs.html"]}
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/breadcrumbs/conf.py b/tests/sites/breadcrumbs/conf.py
@@ -30,3 +30,6 @@
     "secondary_sidebar_items": ["breadcrumbs"],
     "article_header_start": ["breadcrumbs"],
 }
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/colors/conf.py b/tests/sites/colors/conf.py
@@ -17,3 +17,6 @@
 html_theme = "pydata_sphinx_theme"
 html_copy_source = True
 html_sourcelink_suffix = ""
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/deprecated/conf.py b/tests/sites/deprecated/conf.py
@@ -27,3 +27,6 @@
 }
 
 html_sidebars = {"section1/index": ["sidebar-nav-bs.html"]}
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/sidebars/conf.py b/tests/sites/sidebars/conf.py
@@ -14,3 +14,6 @@
 html_sidebars = {
     "section2/no-sidebar": [],  # Turn off primary/left sidebar
 }
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/test_included_toc/conf.py b/tests/sites/test_included_toc/conf.py
@@ -13,3 +13,6 @@
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "pydata_sphinx_theme"
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/test_navbar_no_in_page_headers/conf.py b/tests/sites/test_navbar_no_in_page_headers/conf.py
@@ -14,3 +14,6 @@
 
 html_copy_source = True
 html_sourcelink_suffix = ""
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}
diff --git a/tests/sites/version_switcher/conf.py b/tests/sites/version_switcher/conf.py
@@ -20,3 +20,6 @@
     },
     "navbar_start": ["navbar-logo", "version-switcher"],
 }
+
+# see https://github.com/sphinx-doc/sphinx/issues/13462
+linkcheck_allowed_redirects = {}

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,12 @@`
`1`	`1`	`{`
`2`	`2`	`"ci": {`
`3`	`3`	`"collect": {`
`4`		`- "staticDistDir": "./audit/_build/kitchen-sink/",`
	`4`	`+ "staticDistDir": "./audit/_build/",`
	`5`	`+ "autodiscoverUrlBlocklist": [`
	`6`	`+ "/genindex.html",`
	`7`	`+ "/search.html",`
	`8`	`+ "/_static/webpack-macros.html"`
	`9`	`+ ],`
`5`	`10`	`"settings": {`
`6`	`11`	`"skipAudits": ["canonical"]`
`7`	`12`	`}`
Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ code.literal {`
`58`	`58`	`}`
`59`	`59`
`60`	`60`	`a > code {`
`61`		`- color: var(--pst-color-inline-code-links);`
	`61`	`+ color: var(--pst-color-link-higher-contrast);`
`62`	`62`
`63`	`63`	`&:hover {`
`64`	`64`	`color: var(--pst-color-link-hover);`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ blockquote {`
`26`	`26`
`27`	`27`	`// Ensure there is enough contrast against the background`
`28`	`28`	`a {`
`29`		`- color: var(--pst-color-inline-code-links);`
	`29`	`+ color: var(--pst-color-link-higher-contrast);`
`30`	`30`	`}`
`31`	`31`
`32`	`32`	`// hack to make the text in the blockquote selectable`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@`
`36`	`36`
`37`	`37`	`// Ensure there is enough contrast against the background`
`38`	`38`	`a {`
`39`		`- color: var(--pst-color-inline-code-links);`
	`39`	`+ color: var(--pst-color-link-higher-contrast);`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	`// The "Switch to stable version" link (styled like a button)`