Feature #3247 link check (#3325)

* Per #3247, adding automated link checking in conjunction with new repo dtcenter/metplus-action-linkcheck

* Resolving error

* Per #3247, add workflow dispatch to the linkcheck PR workflow too

* Per #3247, combine workflows into one file

* Per #3247, adding documentation for the new custom/composite action.

* Per #3247, added documentation for Check Documentation Links (linkcheck.yml)

* Per #3247, set install-package: true in linkcheck workflow to resolved ModuleNotFoundError during linkcheck

* Trigger fresh linkcheck run to pick up updated action

* Per #3247, resolve syntax error in yml file

* Trigger fresh linkcheck run to pick up updated action

* Trigger fresh linkcheck run to pick up updated action

* Remove reference to a specific day of week

Co-authored-by: John Halley Gotway <johnhg@ucar.edu>

* Per #3247, made suggested updates by reviewer.

* Per #3247, udpate name to use camel-case to match naming conventions of other METplus actions per reviewer suggestion.

* Per #3247, update checkout version to be 6 from 4

* Per #3247, removed extra whitespace and extra dash.

---------

Co-authored-by: John Halley Gotway <johnhg@ucar.edu>

Author: jprestop

.github/workflows/linkcheck.yml

@@ -0,0 +1,19 @@
+name: Linkcheck
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  pull_request:
+    paths:
+      - 'docs/**'
+  workflow_dispatch: {}
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtcenter/metplus-action-linkcheck@v1
+        with:
+          fail-on-broken-links: 'true'
+          upload-artifact: 'true'
+          install-package: 'true'

docs/Contributors_Guide/continuous_integration.rst

@@ -6,6 +6,7 @@ METplus utilizes GitHub Actions to run processes automatically when changes
 are pushed to GitHub. These tasks include:
 
 * Building documentation to catch warnings/errors
+* Checking documentation for broken external links
 * Building a Docker image to run tests
 * Creating/Updating Docker data volumes with new input data used for tests
 * Running unit tests
@@ -77,6 +78,42 @@ at the bottom of the workflow summary page when the workflow has completed.
 
 .. figure:: figure/ci-doc-artifacts.png
 
+.. _cg-ci-linkcheck:
+
+Check Documentation Links (linkcheck.yml)
+-----------------------------------------
+
+METplus documentation contains many links to external resources, such as
+academic papers, related software packages, and other websites. Over time,
+these external links can break as pages are moved or removed. This workflow
+runs Sphinx's ``linkcheck`` builder to identify broken links in the
+documentation.
+
+This workflow is defined in each of the METplus component repositories.
+It calls a :ref:`cg-ci-custom-actions` action,
+`dtcenter/metplus-action-linkcheck <https://github.com/dtcenter/metplus-action-linkcheck>`_,
+so that the logic to install documentation dependencies and run the
+``linkcheck`` builder does not need to be duplicated across repositories.
+
+This workflow is triggered by:
+
+* A weekly **schedule**, so that link rot is caught even when
+  no documentation changes have been made
+* A **pull_request** event for changes to files under the **docs** directory,
+  so that new or edited links are checked before a pull request is merged
+* A manual **workflow_dispatch** event, so that a developer can run the check
+  on demand against any branch
+
+If broken links are found, the workflow job fails, as indicated by a red X,
+and the full ``linkcheck`` report is made available for download as a
+GitHub Actions artifact so it can be reviewed.
+
+Some links may be intentionally excluded from this check. For example, a link
+may be valid but block automated/non-browser requests, or may point to a
+resource that is only reachable from an internal network. These exclusions
+are configured per repository in the ``linkcheck_ignore`` variable in that
+repository's **docs/conf.py** file.
+
 .. _cg-ci-sonarqube:
 
 SonarQube (sonarqube.yml)
@@ -1591,6 +1628,8 @@ the truth data, an artifact is created for the use case group. It contains
 files that differ so that the user can download and examine them. Files that
 are only found in one or the other are also included.
 
+.. _cg-ci-custom-actions:
+
 Custom GitHub Actions
 =====================
 
@@ -1600,6 +1639,11 @@ Each custom action is stored in its own GitHub repository.
 Navigate to the GitHub repository for a custom action to learn more about
 using it.
 
+Custom actions in METplus may be implemented as Docker container actions,
+JavaScript actions, or composite actions. Composite actions are the
+preferred approach for new development going forward, since they avoid
+Docker image build/pull overhead and are not restricted to Linux runners.
+
 Free Disk Space
 ---------------
 
@@ -1638,3 +1682,11 @@ Create Checksum for Release
 Add a checksum to a release
 
 `dtcenter/metplus-action-release-checksum <https://github.com/dtcenter/metplus-action-release-checksum>`_
+
+Check Documentation Links
+-------------------------
+
+Runs Sphinx's ``linkcheck`` builder against a METplus component's
+documentation to identify broken external links.
+
+`dtcenter/metplus-action-linkcheck <https://github.com/dtcenter/metplus-action-linkcheck>`_

docs/conf.py

@@ -230,6 +230,26 @@
 def setup(app):
     app.add_css_file("custom.css")
 
+# -- linkcheck builder configuration ----------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+
+linkcheck_timeout = 10
+linkcheck_retries = 2
+linkcheck_workers = 8
+
+linkcheck_ignore = [
+    # add regex patterns for URLs that should be skipped, e.g.:
+    # r'https://dtcenter\.org/.*',   # verify first — some DTC pages may block
+    # r'https://www\.weather\.gov/.*',      # NWS pages sometimes rate-limit or redirect oddly
+]
+
+linkcheck_allowed_redirects = {
+    # map of regex -> regex for redirects that are fine to follow
+}
+
+linkcheck_anchors = True
+linkcheck_anchors_ignore = ['^!']
+
 # -- Replace values in docs ------------------------------------------------------------
 rst_epilog = f"""
 .. |copyright|    replace:: {copyright}