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

@@ -18,6 +18,22 @@ All plotting is handled through the :class:`pygmt.Figure` class and its methods.
 
     Figure
 
+Clipping
+~~~~~~~~
+
+Use :attr:`pygmt.Figure.clip` to define clipping paths within a ``with`` block.
+
+.. autosummary::
+    :toctree: generated
+
+    Figure.clip
+    Figure.clip.land
+    Figure.clip.water
+    Figure.clip.dcw
+    Figure.clip.solar
+    Figure.clip.polygon
+    Figure.clip.mask
+
 Plotting figure elements
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

pygmt/figure.py

@@ -11,6 +11,7 @@
 from pygmt._typing import PathLike
 from pygmt.src.basemap import basemap as _basemap
 from pygmt.src.choropleth import choropleth as _choropleth
+from pygmt.src.clip import ClipAccessor
 from pygmt.src.coast import coast as _coast
 from pygmt.src.colorbar import colorbar as _colorbar
 from pygmt.src.contour import contour as _contour
@@ -164,6 +165,16 @@ def region(self) -> np.ndarray:
             wesn = lib.extract_region()
         return wesn
 
+    @property
+    def clip(self) -> ClipAccessor:
+        """
+        Access clipping helpers for plotting inside or outside a path.
+
+        Use methods of this accessor as context managers, for example
+        ``with fig.clip.land():``.
+        """
+        return ClipAccessor(self)
+
     def savefig(
         self,
         fname: PathLike,

pygmt/src/__init__.py

@@ -6,6 +6,7 @@
 # Figure plotting methods are attached in pygmt/figure.py and are not exported here.
 from pygmt.src.binstats import binstats
 from pygmt.src.blockm import blockmean, blockmedian, blockmode
+from pygmt.src.clip import ClipAccessor
 from pygmt.src.config import config
 from pygmt.src.dimfilter import dimfilter
 from pygmt.src.filter1d import filter1d