MAINT - Workflows updates (#2174)

This PR _should_ be the last of a series of improvements to our CI:

1. We have been having intermittent failures on our `docs-check`
workflow when trying to check links for `gnu` such as:

	```

/home/runner/work/pydata-sphinx-theme/pydata-sphinx-theme/docs/community/topics/i18n.rst:112:
WARNING: broken link:
https://www.gnu.org/software/gettext/manual/gettext.html#Fuzzy-Entries
(HTTPSConnectionPool(host='www.gnu.org', port=443): Max retries exceeded
with url: /software/gettext/manual/gettext.html (Caused by
NewConnectionError('<urllib3.connection.HTTPSConnection object at
0x7f6d203efb10>: Failed to establish a new connection: [Errno 101]
Network is unreachable')))
	```

	This PR tries to fix the timeout/retry issues.

2. Remove the RTD preview action that adds the link to the PR comment,
as it has been failing despite having the correct permissions (and it
seems RTD folks plan to move this to RTD directly
readthedocs/readthedocs.org#11780)
3. Fixes the last trigger-related issues after changing the `coverage`
workflow to `workflow_call` so we get our coverage comments again (I
have a PR in my repo with this working again
trallard#2)

---------

Co-authored-by: Daniel McCloy <[email protected]>

Author: trallard

.github/workflows/CI.yml

@@ -195,12 +195,16 @@ jobs:
   # we might want to pin the SHA once merged
   coverage-comment:
     # Important: make sure to update the SHA after making any changes to the coverage workflow
-    uses: pydata/pydata-sphinx-theme/.github/workflows/coverage.yml@4a1e7898d6c92dade5e489684277ab4ffd0eb053
+    # removing pin to test changes
+    uses: ./.github/workflows/coverage.yml
     needs: [coverage]
     # ensures this runs even if the coverage step does not continue - e.g. the
     # default coverage action will fail at first for external PRs, this is a workaround
     # to ensure the comment is posted
-    if: ${{ always() }}
+    if: ${{ github.event.name == 'pull_request'}}
+    with:
+      # this is the workflow run ID of the `CI.yml` workflow
+      workflow_run_id: ${{ github.event.workflow_run.id }}
     permissions:
       contents: write
       pull-requests: write

.github/workflows/coverage.yml

@@ -2,12 +2,15 @@ name: Post coverage comment
 
 on:
   workflow_call:
-
+    inputs:
+      # this is the workflow run ID of the `CI.yml` workflow
+      workflow_run_id:
+        required: true
+        type: string
 jobs:
   test:
     name: "Display code coverage"
     runs-on: ubuntu-latest
-    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
     permissions:
       pull-requests: write
       contents: write # needed to edit the comment vs opening multiple ones
@@ -21,7 +24,7 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           REPO: ${{ github.repository }}
-          WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }}
+          WORKFLOW_RUN_ID: ${{ inputs.workflow_run_id }}
 
       # this needs the .coverage file so we download from the CI workflow artifacts
       - name: "Download coverage data 📥"
@@ -30,7 +33,7 @@ jobs:
           pattern: coverage-data-*
           merge-multiple: true
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          run-id: ${{ github.event.workflow_run.id }}
+          run-id: ${{ inputs.workflow_run_id }}
 
       - name: "Check downloaded files"
         run: ls -R
@@ -39,4 +42,4 @@ jobs:
         uses: py-cov-action/python-coverage-comment-action@b2eb38dd175bf053189b35f738f9207278b00925
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}
+          GITHUB_PR_RUN_ID: ${{ inputs.workflow_run_id }}

.github/workflows/rtd-preview-link.yml

@@ -358,6 +358,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     }
 
 
+# -- linkcheck options ---------------------------------------------------------
+
 linkcheck_anchors_ignore = [
     # match any anchor that starts with a '/' since this is an invalid HTML anchor
     r"\/.*",
@@ -399,3 +401,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     r"http://www.yahoo.com": "https://www.yahoo.com/",
     r"https://feature-engine.readthedocs.io/": "https://feature-engine.trainindata.com/en/latest/",
 }
+
+# we have had issues with linkcheck timing and retries on www.gnu.org
+linkcheck_retries = 3
+linkcheck_timeout = 50