MAINT - Fix linkcheck failures (#2207)

trallard · Tania Allard · stevepiercy · web-flow · commit 6e536c27264e · 2025-05-14T21:05:09.000-07:00
We have a few broken links/redirects in the docs that are currently
causing the CI to fail. This PR should fix these.

---------

Co-authored-by: Tania Allard &lt;tallard@quansight.com&gt;
Co-authored-by: Steve Piercy &lt;web@stevepiercy.com&gt;
Co-authored-by: gabalafou &lt;gabriel@fouasnon.com&gt;
Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
diff --git a/docs/community/design-system.md b/docs/community/design-system.md
@@ -167,7 +167,7 @@ color and typography in the PyData Sphinx theme:
       including font stacks, sizes, and weights in the
       [`fonts.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss).
    2. You can find all the PyData Sphinx theme colors in the
-      [`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
+      [`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
 2. **Figma Design File:** The Figma file contains the visual design and specifications
    for the typography styles, including font sizes, line heights,
    and spacing used throughout the theme. It also includes our color palette and its use cases, as well as details on interactive components and their states.
diff --git a/docs/community/inspiration.md b/docs/community/inspiration.md
@@ -19,7 +19,7 @@ When making new decisions about design and UI/UX, we often consult these themes
   link: https://docs.docker.com/
   image: ../_static/inspiration/docker-mark-blue.svg
 - title: "**PyTorch**"
-  link: https://pytorch.org/docs/stable/index.html
+  link: https://docs.pytorch.org/docs/stable/index.html
   image: https://docs.pytorch.org/docs/stable/_static/images/logo-dark.svg
 - title: "**Docasaurus**"
   link: https://docusaurus.io/docs
diff --git a/docs/community/topics/assets.md b/docs/community/topics/assets.md
@@ -52,5 +52,5 @@ Our Webpack build generates a collection of [Jinja macros](https://jinja.pallets
 
 These macros are imported in the main `layout.html` file, and then inserted at various places on the page to link the static assets.
 
-Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload), meaning that the browser begins requesting these resources before they're needed.
+Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload), meaning that the browser begins requesting these resources before they're needed.
 In particular, our JavaScript assets are preloaded in `<head>`, and the scripts are loaded at the end of `<body>`.
diff --git a/docs/conf.py b/docs/conf.py
@@ -377,6 +377,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     # get a 403 on CI
     "https://canvas.workday.com/styles/tokens/type",
     "https://unsplash.com/",
+    r"https://www.gnu.org/software/gettext/.*",
 ]
 
 linkcheck_allowed_redirects = {
@@ -389,7 +390,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     r"https://virtualenv.pypa.io/": "https://virtualenv.pypa.io/en/latest/",
     # catching redirects in rtd
     r"https://[A-Za-z\d_\-\.]+.readthedocs.io/": r"https://[A-Za-z\d_\-\.]+\.readthedocs\.io(/en)?/(stable|latest)/",
-    r"https://readthedocs.org/": r"https://about.readthedocs.com\?ref=readthedocs.org",
+    r"https://readthedocs.org/": r"https://about.readthedocs.com/\?ref=app.readthedocs.org",
     r"https://app.readthedocs.org/dashboard/": r"https://app.readthedocs.org/accounts/login/\?next=/dashboard/",
     # miscellanenous urls
     r"https://python.arviz.org/": "https://python.arviz.org/en/stable/",
@@ -398,8 +399,10 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     r"https://gitlab.com": "https://about.gitlab.com/",
     r"http://www.yahoo.com": "https://www.yahoo.com/",
     r"https://feature-engine.readthedocs.io/": "https://feature-engine.trainindata.com/en/latest/",
+    r"https://picsum.photos/": r"https://fastly.picsum.photos/",
 }
 
 # we have had issues with linkcheck timing and retries on www.gnu.org
-linkcheck_retries = 3
-linkcheck_timeout = 50
+linkcheck_retries = 1
+linkcheck_timeout = 5
+linkcheck_report_timeouts_as_broken = True
diff --git a/docs/user_guide/fonts.rst b/docs/user_guide/fonts.rst
@@ -48,7 +48,7 @@ The default body and header fonts can be changed as follows:
       {% endblock %}
 
     Your text may quickly show up as "unstyled" before the fonts are loaded. To reduce this, you may wish to explore options for
-    `preloading content <https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload>`__,
+    `preloading content <https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/preload>`__,
     specifically the binary font files. This ensures the files will be loaded
     before the CSS is parsed, but should be used with care.
 
