POC: Figure.clip: Clip paths by polygons, land or water

doc/_templates/autosummary/class.rst

@@ -8,8 +8,8 @@
 .. rubric:: Attributes
 
 {% for item in attributes %}
-.. autoattribute::
-    {{ objname }}.{{ item }}
+.. autoattribute:: {{ objname }}.{{ item }}
+    :no-index:
 {% endfor %}
 {% endif %}
 

doc/api/index.rst

@@ -25,6 +25,7 @@ Plotting map elements
     :toctree: generated
 
     Figure.basemap
+    Figure.clip
     Figure.coast
     Figure.colorbar
     Figure.hlines
@@ -238,6 +239,7 @@ Miscellaneous
 
     which
     show_versions
+    src.ClipAccessor
 
 Datasets
 --------

pygmt/figure.py

@@ -10,6 +10,7 @@
 from typing import Literal, overload
 
 from pygmt._typing import PathLike
+from pygmt.src import ClipAccessor
 
 try:
     import IPython
@@ -145,6 +146,15 @@ def region(self) -> np.ndarray:
             wesn = lib.extract_region()
         return wesn
 
+    @property
+    def clip(self) -> ClipAccessor:
+        """
+        Set up a clipping path and only plot data inside/outside it.
+
+        See :class:`pygmt.src.clip.ClipAccessor <ClipAccessor>` for the usage.
+        """
+        return ClipAccessor(self)
+
     def savefig(
         self,
         fname: PathLike,

pygmt/src/__init__.py

@@ -5,6 +5,7 @@
 from pygmt.src.basemap import basemap
 from pygmt.src.binstats import binstats
 from pygmt.src.blockm import blockmean, blockmedian, blockmode
+from pygmt.src.clip import ClipAccessor
 from pygmt.src.coast import coast
 from pygmt.src.colorbar import colorbar
 from pygmt.src.config import config