Improve documentation of SubplotGrid methods

Author: lukelbd

docs/basics.py

@@ -339,7 +339,7 @@
 # figures with more than one column and row, a 1D `~numpy.ndarray` for single-column or
 # row figures, or an `~matplotlib.axes.Axes` for single-subplot figures. In ProPlot,
 # `~proplot.figure.Figure.subplots` returns a `~proplot.gridspec.SubplotGrid` that
-# unifies these three possible return values:
+# unifies these possible return values:
 #
 # * `~proplot.gridspec.SubplotGrid` permits array-like 2D indexing, e.g.
 #   ``axs[1, 0]``. Indexing the `~proplot.gridspec.SubplotGrid` is similar
@@ -388,7 +388,6 @@
 axs[1, :1].format(fc='sky blue')
 axs[-1, -1].format(fc='gray2', grid=False)
 
-
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_rc:
 #

proplot/axes/base.py

@@ -162,9 +162,10 @@
 
 
 # Inset docstring
+# NOTE: Used by SubplotGrid.inset_axes
 _inset_docstring = """
-Return an inset `CartesianAxes`. This is similar to the builtin
-`~matplotlib.axes.Axes.inset_axes` but includes some extra options.
+Add an inset axes.
+This is similar to `matplotlib.axes.Axes.inset_axes`.
 
 Parameters
 ----------
@@ -187,6 +188,11 @@
 zoom_kw : dict, optional
     Passed to `~Axes.indicate_inset_zoom`.
 
+Returns
+-------
+proplot.axes.Axes
+    The inset axes.
+
 Other parameters
 ----------------
 **kwargs
@@ -196,6 +202,7 @@
 
 
 # Panel docstring
+# NOTE: Used by SubplotGrid.panel_axes
 _panel_loc_docstring = """
     ==========  =====================
     Location    Valid keys
@@ -207,7 +214,7 @@
     ==========  =====================
 """
 _panel_docstring = """
-Return a panel drawn along the edge of this axes.
+Add a panel along the edge of the axes.
 
 Parameters
 ----------
@@ -235,7 +242,7 @@
 
 Returns
 -------
-`~proplot.axes.CartesianAxes`
+proplot.axes.CartesianAxes
     The panel axes.
 """
 docstring._snippet_manager['axes.panel_loc'] = _panel_loc_docstring
@@ -320,11 +327,10 @@
 figtitle
     Alias for `suptitle`.
 suptitle : str, optional
-    The figure "super" title, centered between the left edge of
-    the lefmost column of subplots and the right edge of the rightmost
-    column of subplots, and automatically offset above figure titles.
-    This is an improvement on matplotlib's "super" title, which just
-    centers the text between figure edges.
+    The figure "super" title, centered between the left edge of the lefmost
+    column of subplots and the right edge of the rightmost column of subplots, and
+    automatically offset above figure titles. This is an improvement on matplotlib's
+    "super" title, which just centers the text between figure edges.
 suptitlepad : float, optional
     The padding between the super title and the axes content in arbitrary
     units (default is points). Default is :rcraw:`suptitle.pad`.
@@ -1315,9 +1321,8 @@ def format(
         **kwargs
     ):
         """
-        Modify the axes title(s), the a-b-c label, row and column labels, and
-        the figure title. Called by the `~proplot.axes.CartesianAxes`,
-        `~proplot.axes.PolarAxes`, and `~proplot.axes.GeoAxes` ``format`` methods.
+        Format the a-b-c label, axes title(s), and background
+        patch, and call `proplot.figure.Figure.format`.
 
         Parameters
         ----------
@@ -1330,20 +1335,20 @@ def format(
 
         Important
         ---------
-        The `abc`, `abcstyle`, `abcloc`, `titleloc`, `titleabove`, `titlepad`,
-        `abctitlepad`, `leftlabelpad`, `toplabelpad`, `rightlabelpad`, and
-        `bottomlabelpad` keywords are :ref:`configuration settings <ug_config>`.
-        We explicitly document these arguments here because it is very common to change
-        them. But many :ref:`other configuration settings <ug_format>` can be passed
-        to ``format`` too.
+        `abc`, `abcstyle`, `abcloc`, `titleloc`, `titleabove`, `titlepad`, and
+        `abctitlepad` are actually :ref:`configuration settings <ug_config>`.
+        We explicitly document these arguments here because it is common to
+        change them for specific axes. But many :ref:`other configuration
+        settings <ug_format>` can be passed to ``format`` too.
 
         See also
         --------
-        proplot.config.Configurator.context
         proplot.axes.CartesianAxes.format
         proplot.axes.PolarAxes.format
         proplot.axes.GeoAxes.format
         proplot.figure.Figure.format
+        proplot.gridspec.SubplotGrid.format
+        proplot.config.Configurator.context
         """
         skip_figure = kwargs.pop('skip_figure', False)  # internal keyword arg
         rc_kw, rc_mode, kwargs = _parse_format(**kwargs)
@@ -1493,9 +1498,10 @@ def inset_axes(
 
     def indicate_inset_zoom(self, **kwargs):
         """
-        Draw lines indicating the zoom range of the inset axes. This is similar
-        to the builtin `~matplotlib.axes.Axes.indicate_inset_zoom` except
-        lines are *refreshed* at draw-time. This is also called automatically
+        Draw lines indicating the zoom range of the inset axes. Must be
+        called from the inset axes rather than the parent axes. This is
+        similar to `matplotlib.axes.Axes.indicate_inset_zoom` except line
+        positions are refreshed at drawtime. This is called automatically
         when ``zoom=True`` is passed to `~Axes.inset_axes`.
 
         Parameters
@@ -1508,7 +1514,7 @@ def indicate_inset_zoom(self, **kwargs):
             The line style for the zoom lines and box outline.
         ec, edgecolor : color-spec, optional
             The color of the zoom lines and box outline.
-        capstyle : {'butt', 'round', 'projecting'}
+        cs, capstyle : {'butt', 'round', 'projecting'}
             The cap style for the zoom lines and box outline.
         zorder : float, optional
             The `zorder <https://matplotlib.org/stable/gallery/misc/zorder_demo.html>`__

proplot/axes/cartesian.py

@@ -38,18 +38,23 @@
 {args} : optional
     Prepended with ``'{x}'`` and passed to `Axes.format`.
 
+Returns
+-------
+CartesianAxes
+    The new axes.
+
 Note
 ----
 This enforces the following default settings:
 
-* Places the old *{x}* axis on the {x1} and the new *{x}*
+* Places the old {x} axis on the {x1} and the new {x}
   axis on the {x2}.
 * Makes the old {x2} spine invisible and the new {x1}, {y1},
   and {y2} spines invisible.
-* Adjusts the *{x}* axis tick, tick label, and axis label positions
+* Adjusts the {x} axis tick, tick label, and axis label positions
   according to the visible spine positions.
-* Syncs the old and new *{y}* axis limits and scales, and makes the
-  new *{y}* axis labels invisible.
+* Syncs the old and new {y} axis limits and scales, and makes the
+  new {y} axis labels invisible.
 """
 _shared_x_keys = dict(
     x='x', x1='bottom', x2='top',
@@ -65,29 +70,36 @@
 )
 
 # Alt docstrings
+# NOTE: Used by SubplotGrid.altx
 _alt_descrip = """
-Return an axes in the same location as this one but whose {x}
-axis is on the {x2}. This is an alias and more intuitive name
-for `~CartesianAxes.twin{y}`, which generates two *{x}* axes
-with a shared ("twin") *{y}* axes.
+Add an axes locked to the same location with a
+distinct {x} axis.
+This is an alias and possibly more intuitive name for
+`~CartesianAxes.twin{y}`, which generates two {x} axes
+with a shared ("twin") {y} axes.
 """
 _alt_docstring = _shared_docstring % {'descrip': _alt_descrip, 'extra': ''}
 docstring._snippet_manager['axes.altx'] = _alt_docstring.format(**_shared_x_keys)
 docstring._snippet_manager['axes.alty'] = _alt_docstring.format(**_shared_y_keys)
 
 # Twin docstrings
+# NOTE: Used by SubplotGrid.twinx
 _twin_descrip = """
-Return an axes in the same location as this one but whose {x}
-axis is on the {x2}. Mimics `matplotlib.axes.Axes.twin{y}`.
+Add an axes locked to the same location with a
+distinct {x} axis.
+This builds upon `matplotlib.axes.Axes.twin{y}`.
 """
 _twin_docstring = _shared_docstring % {'descrip': _twin_descrip, 'extra': ''}
 docstring._snippet_manager['axes.twinx'] = _twin_docstring.format(**_shared_y_keys)
 docstring._snippet_manager['axes.twiny'] = _twin_docstring.format(**_shared_x_keys)
 
 # Dual docstrings
+# NOTE: Used by SubplotGrid.dualx
 _dual_descrip = """
-Return a secondary *{x}* axis for denoting equivalent *{x}*
-coordinates in *alternate units*.
+Add an axes locked to the same location whose {x} axis denotes
+equivalent coordinates in alternate units.
+This is an alternative to `matplotlib.axes.Axes.secondary_{x}axis` with
+additional convenience features.
 """
 _dual_extra = """
 funcscale : callable, 2-tuple of callables, or scale-spec
@@ -801,6 +813,7 @@ def format(
         See also
         --------
         proplot.axes.Axes.format
+        proplot.figure.Figure.format
         proplot.config.Configurator.context
 
         Note

proplot/axes/plot.py

@@ -127,7 +127,7 @@
 %(plot.args_1d_shared)s
 order : {{'C', 'F'}}, optional
     If ``'C'`` (C-style row-major order), `z` coordinates should be shaped
-    ``(y, x)``. If ``'F'`` (Fortran-style column-major order) `z` coordinates
+    ``(y, x)``. If ``'F'`` (fortran-style column-major order) `z` coordinates
     should be shaped ``(x, y)``. Default is ``'C'``.
 globe : bool, optional
     For `proplot.axes.GeoAxes` only. Whether to enforce global coverage.

proplot/figure.py

@@ -1411,28 +1411,38 @@ def format(
         rowlabels=None, collabels=None, **kwargs,  # aliases
     ):
         """
-        Call the ``format`` command for the input axes or
-        for every subplot in the figure.
+        Format the figure labels and title and call ``format`` for
+        the input axes. By default the numbered subplots are used.
 
         Parameters
         ----------
         axs : sequence of `~proplot.axes.Axes`, optional
-            A sequence of axes. By default the numbered subplots are used.
+            The axes to format.
         %(figure.format)s
 
         Other parameters
         ----------------
         %(axes.format)s
         %(axes.rc)s
         **kwargs
-            Passed to the ``format`` command of each axes.
+            Passed to the projection-specific ``format`` command for each axes.
+
+        Important
+        ---------
+        `leftlabelpad`, `toplabelpad`, `rightlabelpad`, and `bottomlabelpad`
+        keywords are actually :ref:`configuration settings <ug_config>`.
+        We explicitly document these arguments here because it is common to
+        change them for specific figures. But many :ref:`other configuration
+        settings <ug_format>` can be passed to ``format`` too.
 
         See also
         --------
         proplot.axes.Axes.format
         proplot.axes.CartesianAxes.format
         proplot.axes.PolarAxes.format
         proplot.axes.GeoAxes.format
+        proplot.gridspec.SubplotGrid.format
+        proplot.config.Configurator.context
         """
         # Initiate context block
         rc_kw, rc_mode, kwargs = _parse_format(**kwargs)