Add a link checker into CI (#1397)

erogluorhan · web-flow · commit ace03d86312f · 2025-11-03T13:49:49.000-07:00
* Update Why Uxarray in Getting Started Overview

* Update the rest of Overview file

* Address one minor comment

* Add link-check into ci.yml

* Fix a broken link in advanced plotting notebook

* Address review comments

* Fix linkcheck errors

* Fix remaining linkcheck errors

* Set timeout to 20 min
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -62,7 +62,56 @@ jobs:
         run: |
           conda list
 
-
       - name: Run Namespace Tests
         run: |
           python -m pytest test
+
+  link-check:
+      runs-on: ubuntu-latest
+      defaults:
+        run:
+          shell: bash -l {0}
+      steps:
+        - name: checkout
+          uses: actions/checkout@v5.0.0
+
+        - name: environment setup
+          id: link-env-setup
+          continue-on-error: true
+          uses: mamba-org/setup-micromamba@0dea6379afdaffa5d528b3d1dabc45da37f443fc # v2
+          with:
+            environment-file: ci/docs.yml
+            cache-environment: true
+            cache-environment-key: "linkcheck-${{env.TODAY}}"
+            create-args: >-
+              python=3.11
+
+        - name: retry environment set up if failed
+          if: steps.link-env-setup.outcome == 'failure'
+          uses: mamba-org/setup-micromamba@0dea6379afdaffa5d528b3d1dabc45da37f443fc # v2
+          with:
+            download-micromamba: false
+            environment-file: ci/docs.yml
+            cache-environment: true
+            cache-environment-key: "linkcheck-${{env.TODAY}}"
+            create-args: >-
+              python=3.11
+
+        - name: Install uxarray
+          run: |
+            python -m pip install . --no-deps
+
+        - name: conda list
+          run: |
+            conda list
+
+        - name: Make docs with linkcheck
+          uses: nick-fields/retry@ce71cc2ab81d554ebbe88c79ab5975992d79ba08 # v3
+          with:
+            timeout_minutes: 20
+            max_attempts: 3
+            command: |
+              eval "$(micromamba shell hook --shell bash)"
+              micromamba activate uxarray-docs
+              cd docs
+              make linkcheck
diff --git a/docs/api.rst b/docs/api.rst
@@ -151,6 +151,8 @@ Methods
    Grid.calculate_total_face_area
    Grid.normalize_cartesian_coordinates
    Grid.construct_face_centers
+   Grid.get_ball_tree
+   Grid.get_kd_tree
    Grid.get_spatial_hash
    Grid.get_faces_containing_point
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -231,6 +231,9 @@ def __getattr__(cls, name):
     "parallel-load-ux-with-dask.ipynb",
 ]
 
+# add links to ignore during link checking
+linkcheck_ignore = [r"https://gmao.gsfc.nasa.gov/gmaoftp/*"]
+
 
 # custom scripts for making a gallery of examples notebooks
 def update_gallery(app: Sphinx):
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -53,9 +53,10 @@ However, this guide might still be missing case-specific details; please do
 not hesitate to reach out to us to consult any such cases.
 
 .. note::
-    Much of the information in this guide has been co-opted from the
-    `GeoCAT <https://geocat.ucar.edu/pages/contributing.html>`_ project and
-    `Project Pythia <https://projectpythia.org/contributing.html>`_.
+    Much of the information in this guide has been co-opted from `Project
+    Pythia <https://projectpythia.org/contributing>`_ and the
+    `GeoCAT-comp <https://geocat-comp.readthedocs.io/en/stable/contrib.html>`_
+    project.
 
 1.3. Project-specific Resources
 -------------------------------
diff --git a/docs/gallery.yml b/docs/gallery.yml
@@ -22,5 +22,5 @@ workflow-examples:
 
 external-examples:
   - title: Unstructured Grid Visualization Cookbook
-    path: https://projectpythia.org/unstructured-grid-viz-cookbook/README.html
+    path: https://projectpythia.org/unstructured-grid-viz-cookbook
     thumbnail: https://raw.githubusercontent.com/ProjectPythia/projectpythia.github.io/main/portal/_static/images/logos/pythia_logo-blue-btext-twocolor.svg
diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst
@@ -30,8 +30,8 @@ grid format, meaning that we encode all supported unstructured grid formats in t
 UGRID conventions at the data loading step.
 
 Specifically, our core functionality is built around horizontally Unstructured Grids as
-defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain
-a mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured
+defined by the 2D Flexible Mesh Topology in the UGRID conventions, which can contain a
+mix of triangles, quadrilaterals, or other geometric faces. These types of Unstructured
 Grids may have structured vertical levels.
 
 
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -7,4 +7,4 @@ Tutorials & Videos
 
 Tutorials
 ---------
-* `Project Pythia Unstructured Grid Visualization Cookbook <https://projectpythia.org/unstructured-grid-viz-cookbook/README.html>`_
+* `Project Pythia Unstructured Grid Visualization Cookbook <https://projectpythia.org/unstructured-grid-viz-cookbook>`_
diff --git a/docs/user-guide/advanced-plotting.ipynb b/docs/user-guide/advanced-plotting.ipynb
@@ -2,54 +2,63 @@
  "cells": [
   {
    "cell_type": "markdown",
-   "source": [
-    "# Advanced Plotting Techniques"
-   ],
+   "id": "6ed8f179fd52f3ff",
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
-   "id": "6ed8f179fd52f3ff"
+   "source": [
+    "# Advanced Plotting Techniques"
+   ]
   },
   {
    "cell_type": "markdown",
+   "id": "d985f5b59e2e6a27",
+   "metadata": {
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
+   },
    "source": [
     "```{seealso}\n",
-    "This section is currently under development. For more information about advanced plotting techniques for unstructured grids, please refer to the [Unstructured Grid Visualuzation Cookbook](https://projectpythia.org/unstructured-grid-viz-cookbook/README.html).\n",
+    "This section is currently under development. For more information about advanced plotting techniques for unstructured grids, please refer to the [Unstructured Grid Visualization Cookbook](https://projectpythia.org/unstructured-grid-viz-cookbook).\n",
     "```"
-   ],
-   "metadata": {
-    "collapsed": false
-   },
-   "id": "d985f5b59e2e6a27"
+   ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "outputs": [],
-   "source": [],
+   "id": "22a8d2939338bdce",
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
-   "id": "22a8d2939338bdce"
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
     "name": "ipython",
-    "version": 2
+    "version": 3
    },
    "file_extension": ".py",
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "2.7.6"
+   "version": "3.13.9"
   }
  },
  "nbformat": 4,
diff --git a/docs/user-guide/data-structures.ipynb b/docs/user-guide/data-structures.ipynb
@@ -23,9 +23,9 @@
    "source": [
     "The core functionality of UXarray revolves around three data structures, which are used for interacting with unstructured grids and the data variables that reside on them.\n",
     "\n",
-    "1. **[`uxarray.Grid`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataArray.html)**: Stores the grid representation (i.e. coordinates, connectivity information, etc.)\n",
-    "2. **[`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataset.html)**: One or more data variable that resided on a grid.\n",
-    "3. **[`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataArray.html)**: A single data variable that resides on a grid \n"
+    "1. **[`uxarray.Grid`](https://uxarray.readthedocs.io/en/latest/generated/uxarray.UxDataArray.html)**: Stores the grid representation (i.e. coordinates, connectivity information, etc.)\n",
+    "2. **[`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataset)**: One or more data variable that resided on a grid.\n",
+    "3. **[`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataarray)**: A single data variable that resides on a grid\n"
    ]
   },
   {
diff --git a/docs/user-guide/grid-formats.rst b/docs/user-guide/grid-formats.rst
@@ -148,7 +148,7 @@ Alfred Wegener Institute, Helmholtz Centre for Polar and Marine Research (AWI),
 
 References
 ----------
-* https://fesom2.readthedocs.io/en/latest/index.html#
+* https://fesom2.readthedocs.io/
 
 HEALPix
 =======
diff --git a/docs/user-guide/mpl.ipynb b/docs/user-guide/mpl.ipynb
@@ -52,8 +52,8 @@
     "## Matplotlib and Cartopy Background\n",
     "\n",
     "To support Matplotlib and Cartopy workflows, UXarray has chosen to provide the necessary conversion functions to represent unstructured grids in formats that can be interpreted by these packages. This means that you as the user are responsible for setting up the figure, adding colorbar, and configuring other aspects of the plotting workflow. Because of this, we will not cover these topics in detail, but recommend reviewing the following resources:\n",
-    "- [**Pythia Foundations:** Matplotlib](https://foundations.projectpythia.org/core/matplotlib.html)\n",
-    "- [**Pythia Foundations:** Cartopy](https://foundations.projectpythia.org/core/cartopy.html)\n",
+    "- [**Pythia Foundations:** Matplotlib](https://foundations.projectpythia.org/core/matplotlib)\n",
+    "- [**Pythia Foundations:** Cartopy](https://foundations.projectpythia.org/core/cartopy)\n",
     "- [Matplotlib Quickstart Guide](https://matplotlib.org/stable/users/explain/quick_start.html)\n"
    ]
   },
diff --git a/docs/user-guide/tree_structures.ipynb b/docs/user-guide/tree_structures.ipynb
@@ -124,7 +124,7 @@
     "\n",
     "* `coordinates` allows us to specify what nodes to build the tree on. We can choose from `nodes`, `face_centers`, or `edge_centers`. Each one will change how the tree is built. `nodes` builds the tree from the corner nodes of the grid, `face_centers` builds the tree from the face centers of each face, and `edge_centers` builds from the center of each edge in the grid. The default is to build from `nodes`. \n",
     "* `coordinate_system` specifies the tree's coordinate type when constructing. We can use either `cartesian`, which uses the `(x, y, z)` coordinate system, or `spherical`, which uses the `(lat, lon)` coordinate system. The default parameter is `spherical`.\n",
-    "* `distance_metric` relates to the distance computation, typically returned as a distance when querying for neighbors. There are a large number of options for us to use. A list of these options can be found [here](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.Grid.get_ball_tree.html). An important note here is that some distance metrics aren't compatible with some coordinate systems. `BallTree` uses the haversine distance as default, which will only work with spherical coordinates and not with cartesian. The default parameter is `haversine`.\n",
+    "* `distance_metric` relates to the distance computation, typically returned as a distance when querying for neighbors. There are a large number of options for us to use. A list of these options can be found [here](https://uxarray.readthedocs.io/en/latest/generated/uxarray.Grid.get_ball_tree.html). An important note here is that some distance metrics aren't compatible with some coordinate systems. `BallTree` uses the haversine distance as default, which will only work with spherical coordinates and not with cartesian. The default parameter is `haversine`.\n",
     "* `reconstruct` is a bool variable that allows the user to reconstruct the tree. As default for performance, if a user calls `get_ball_tree` and a tree has already been created, it will simply use that one. If `reconstruct` is set to `True`, it will override this and reconstruct the tree. The default parameter is `False`."
    ]
   },
@@ -300,9 +300,7 @@
      "width": 100
     }
    },
-   "source": [
-    "The KDTree structure is a binary search tree useful for low-dimensional data. Its implementation is almost identical to BallTree, and the parameters are identical. An important note is that the different allowed inputs for `distance_metric` change between the trees. For KDTree allowed `distance_metrics` can be found [here](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.Grid.get_kd_tree.html). We can call it using `get_kd_tree()`. Generally, KDTree is going to be slower than BallTree, and it is recommended to use BallTree for most im"
-   ]
+   "source": "The KDTree structure is a binary search tree useful for low-dimensional data. Its implementation is almost identical to BallTree, and the parameters are identical. An important note is that the different allowed inputs for `distance_metric` change between the trees. For KDTree allowed `distance_metrics` can be found [here](https://uxarray.readthedocs.io/en/latest/generated/uxarray.Grid.get_kd_tree.html). We can call it using `get_kd_tree()`. Generally, KDTree is going to be slower than BallTree, and it is recommended to use BallTree for most im"
   },
   {
    "cell_type": "code",

Original file line number	Diff line number	Diff line change
`@@ -231,6 +231,9 @@ def __getattr__(cls, name):`
`231`	`231`	`"parallel-load-ux-with-dask.ipynb",`
`232`	`232`	`]`
`233`	`233`
	`234`	`+# add links to ignore during link checking`
	`235`	`+linkcheck_ignore = [r"https://gmao.gsfc.nasa.gov/gmaoftp/*"]`
	`236`	`+`
`234`	`237`
`235`	`238`	`# custom scripts for making a gallery of examples notebooks`
`236`	`239`	`def update_gallery(app: Sphinx):`
Original file line number	Diff line number	Diff line change
`@@ -23,9 +23,9 @@`
`23`	`23`	`"source": [`
`24`	`24`	`"The core functionality of UXarray revolves around three data structures, which are used for interacting with unstructured grids and the data variables that reside on them.\n",`
`25`	`25`	`"\n",`
`26`		- "1. [`uxarray.Grid`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataArray.html): Stores the grid representation (i.e. coordinates, connectivity information, etc.)\n",
`27`		- "2. [`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataset.html): One or more data variable that resided on a grid.\n",
`28`		- "3. [`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/user_api/generated/uxarray.UxDataArray.html): A single data variable that resides on a grid \n"
	`26`	+ "1. [`uxarray.Grid`](https://uxarray.readthedocs.io/en/latest/generated/uxarray.UxDataArray.html): Stores the grid representation (i.e. coordinates, connectivity information, etc.)\n",
	`27`	+ "2. [`uxarray.UxDataset`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataset): One or more data variable that resided on a grid.\n",
	`28`	+ "3. [`uxarray.UxDataArray`](https://uxarray.readthedocs.io/en/latest/api.html#uxdataarray): A single data variable that resides on a grid\n"
`29`	`29`	`]`
`30`	`30`	`},`
`31`	`31`	`{`