Merge remote-tracking branch 'origin/main' into singularity-env-sourcing

.github/workflows/SCHED_docs_linkcheck.yml

@@ -29,4 +29,6 @@ jobs:
           make -C doc relnotes
           make -C doc html
       - name: Run Sphinx linkcheck on documentation
-        run: make -C doc linkcheck || make -C doc linkcheck || make -C doc linkcheck  # simple "retry 3 times" - for flaky links
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: make -C doc linkcheck

doc/conf.py

@@ -45,6 +45,26 @@
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 numpydoc_class_members_toctree = False
 
+# -- Options for linkcheck ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+linkcheck_retries = 3  # Retry 3 times before considering a link broken
+linkcheck_workers = 1  # Limit the number of workers to avoid hitting rate limits
+linkcheck_ignore = [
+    # It is easy to hit the rate limit of stackoverflow
+    # Let's assume that stackoverflows does not move its supposedly permanent links
+    "https://stackoverflow.com",
+    # Its also easy to hit the rate limit of github
+    # We do have quite a lot of links to our own github repo
+    # For now, let's avoid checking these
+    "https://github.com/DeiC-HPC/cotainr",
+]
+if "GITHUB_TOKEN" in os.environ:
+    # Authenticate with GitHub token in GitHub Actions to avoid hitting rate limits
+    # It is not entirely clear if this has any effect outside of api.github.com, though...
+    linkcheck_request_headers = {
+        "https://github.com": {"Authorization": f"token {os.environ['GITHUB_TOKEN']}"}
+    }
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

doc/development/test_suite_ci_cd.rst

@@ -89,7 +89,7 @@ The following CI `workflows <https://docs.github.com/en/actions/using-workflows/
 
 Continuous Delivery (CD)
 ------------------------
-Continuous Delivery (CD) is handled partly via `GitHub Actions <https://docs.github.com/en/actions>`_, partly via the a `Read the Docs webhook integration <https://docs.readthedocs.io/en/stable/integrations.html>`_ to the `cotainr` GitHub repository: https://github.com/DeiC-HPC/cotainr/.
+Continuous Delivery (CD) is handled partly via `GitHub Actions <https://docs.github.com/en/actions>`_, partly via the a `Read the Docs webhook integration <https://docs.readthedocs.io/en/stable/continuous-deployment.html>`_ to the `cotainr` GitHub repository: https://github.com/DeiC-HPC/cotainr/.
 
 Read the Docs continuous documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~