DOC [ci doc]

jklymak · jklymak · commit efc2309571ce · 2023-08-30T08:48:07.000-07:00
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1503,6 +1503,11 @@ def add_gridspec(self, nrows=1, ncols=1, **kwargs):
         """
         Create a low-level `.GridSpec` that has this figure as a parent.
 
+        This is a low-level API, allowing you to create a gridspec and
+        subsequently add subplots based on the gridspec. Most users do
+        not need that freedom and should use the higher-level methods
+        `~.Figure.subplots` or `~.Figure.subplot_mosaic`.
+
         Parameters
         ----------
         nrows : int, default: 1
