GMTDataArrayAccessor: Add inline examples for setting GMT specific properties (#2370)

pygmt/accessors.py

@@ -9,20 +9,43 @@
 @xr.register_dataarray_accessor("gmt")
 class GMTDataArrayAccessor:
     """
-    This is the GMT extension for :class:`xarray.DataArray`.
+    GMT extension for :class:`xarray.DataArray`.
 
-    You can access various GMT specific metadata about your grid as follows:
+    The extension provides easy ways to access and change the GMT specific
+    properties about grids. Currently, two properties are available:
+
+    - ``registration``: Gridline (0) or Pixel (1) registration
+    - ``gtype``: Cartesian (0) or Geographic (1) coordinate system
+
+    You can access these GMT specific properties about your grid as follows:
 
     >>> from pygmt.datasets import load_earth_relief
     >>> # Use the global Earth relief grid with 1 degree spacing
     >>> grid = load_earth_relief(resolution="01d", registration="pixel")
-
     >>> # See if grid uses Gridline (0) or Pixel (1) registration
     >>> grid.gmt.registration
     1
     >>> # See if grid uses Cartesian (0) or Geographic (1) coordinate system
     >>> grid.gmt.gtype
     1
+
+    You can also set the GMT specific properties for grids created by yourself:
+
+    >>> import numpy as np
+    >>> import pygmt
+    >>> import xarray as xr
+    >>> # creata a DataArray in gridline coordinates of sin(lon) * cos(lat)
+    >>> interval = 2.5
+    >>> lat = np.arange(90, -90 - interval, -interval)
+    >>> lon = np.arange(0, 360 + interval, interval)
+    >>> longrid, latgrid = np.meshgrid(lon, lat)
+    >>> data = np.sin(np.deg2rad(longrid)) * np.cos(np.deg2rad(latgrid))
+    >>> grid = xr.DataArray(
+    ...     data, coords=[("latitude", lat), ("longitude", lon)]
+    ... )
+    >>> # set it to a gridline-registered geographic grid
+    >>> grid.gmt.registration = 0
+    >>> grid.gmt.gtype = 1
     """
 
     def __init__(self, xarray_obj):
@@ -51,8 +74,8 @@ def registration(self, value):
             self._registration = value
         else:
             raise GMTInvalidInput(
-                f"Invalid grid registration value: {value}, should be a boolean of "
-                "either 0 for Gridline registration or 1 for Pixel registration"
+                f"Invalid grid registration value: {value}, should be either "
+                "0 for Gridline registration or 1 for Pixel registration."
             )
 
     @property
@@ -69,6 +92,6 @@ def gtype(self, value):
             self._gtype = value
         else:
             raise GMTInvalidInput(
-                f"Invalid coordinate system type: {value}, should be a boolean of "
-                "either 0 for Cartesian or 1 for Geographic"
+                f"Invalid coordinate system type: {value}, should be "
+                "either 0 for Cartesian or 1 for Geographic."
             )