Add shading to grdview gallery example

examples/gallery/grid/grdview_surface.py

@@ -8,7 +8,8 @@
 elevation angle of the view. We provide a list of two arguments to ``frame`` — the
 second argument, prepended with ``"z"``, specifies the :math:`z`-axis frame attributes.
 Specifying the same scale for the ``projection`` and ``zcale`` arguments ensures equal
-axis scaling.
+axis scaling. The ``shading`` argument specifies illumination; here we choose an azimuth of
+45° with ``shading="+a45"``.
 """
 
 import pygmt
@@ -44,7 +45,8 @@ def ackley(x, y):
     zscale=f"{SCALE}i",
     surftype="s",
     cmap="roma",
-    perspective="135/30",
+    perspective=[135, 30],  # Azimuth southeast (135°), at elevation 30°
+    shading="+a45",
 )
 
 fig.show()

pygmt/base_plotting.py

@@ -336,6 +336,7 @@ def grdimage(self, grid, **kwargs):
         Wm="meshpen",
         Wf="facadepen",
         p="perspective",
+        I="shading",
     )
     @kwargs_to_strings(R="sequence", p="sequence")
     def grdview(self, grid, **kwargs):
@@ -403,6 +404,15 @@ def grdview(self, grid, **kwargs):
             ``'[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]'``.
             Select perspective view.
 
+        shading : str
+            Provide the name of a grid file with intensities in the (-1,+1)
+            range, or a constant intensity to apply everywhere (affects the
+            ambient light). Alternatively, derive an intensity grid from the
+            input data grid reliefgrid via a call to ``grdgradient``; append
+            ``+aazimuth``, ``+nargs``, and ``+mambient`` to specify azimuth,
+            intensity, and ambient arguments for that module, or just give
+            ``+d`` to select the default arguments (``+a-45+nt1+m0``).
+
         """
         kwargs = self._preprocess(**kwargs)
         kind = data_kind(grid, None, None)