Merge pull request matplotlib#26349 from anntzer/sd

Tweak Sankey docs.

Author: timhoffm

lib/matplotlib/sankey.py

@@ -49,7 +49,7 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25,
         that there is consistent alignment and formatting.
 
         In order to draw a complex Sankey diagram, create an instance of
-        :class:`Sankey` by calling it without any kwargs::
+        `Sankey` by calling it without any kwargs::
 
             sankey = Sankey()
 
@@ -109,8 +109,8 @@ def __init__(self, ax=None, scale=1.0, unit='', format='%G', gap=0.25,
             magnitude of the sum of connected flows cannot be greater than
             *tolerance*.
         **kwargs
-            Any additional keyword arguments will be passed to :meth:`add`,
-            which will create the first subdiagram.
+            Any additional keyword arguments will be passed to `add`, which
+            will create the first subdiagram.
 
         See Also
         --------
@@ -780,35 +780,27 @@ def finish(self):
         Adjust the axes and return a list of information about the Sankey
         subdiagram(s).
 
-        Return value is a list of subdiagrams represented with the following
-        fields:
-
-          ===============   ===================================================
-          Field             Description
-          ===============   ===================================================
-          *patch*           Sankey outline (an instance of
-                            :class:`~matplotlib.patches.PathPatch`)
-          *flows*           values of the flows (positive for input, negative
-                            for output)
-          *angles*          list of angles of the arrows [deg/90]
-                            For example, if the diagram has not been rotated,
-                            an input to the top side will have an angle of 3
-                            (DOWN), and an output from the top side will have
-                            an angle of 1 (UP).  If a flow has been skipped
-                            (because its magnitude is less than *tolerance*),
-                            then its angle will be *None*.
-          *tips*            array in which each row is an [x, y] pair
-                            indicating the positions of the tips (or "dips") of
-                            the flow paths
-                            If the magnitude of a flow is less the *tolerance*
-                            for the instance of :class:`Sankey`, the flow is
-                            skipped and its tip will be at the center of the
-                            diagram.
-          *text*            :class:`~matplotlib.text.Text` instance for the
-                            label of the diagram
-          *texts*           list of :class:`~matplotlib.text.Text` instances
-                            for the labels of flows
-          ===============   ===================================================
+        Returns a list of subdiagrams with the following fields:
+
+        ========  =============================================================
+        Field     Description
+        ========  =============================================================
+        *patch*   Sankey outline (a `~matplotlib.patches.PathPatch`).
+        *flows*   Flow values (positive for input, negative for output).
+        *angles*  List of angles of the arrows [deg/90].
+                  For example, if the diagram has not been rotated,
+                  an input to the top side has an angle of 3 (DOWN),
+                  and an output from the top side has an angle of 1 (UP).
+                  If a flow has been skipped (because its magnitude is less
+                  than *tolerance*), then its angle will be *None*.
+        *tips*    (N, 2)-array of the (x, y) positions of the tips (or "dips")
+                  of the flow paths.
+                  If the magnitude of a flow is less the *tolerance* of this
+                  `Sankey` instance, the flow is skipped and its tip will be at
+                  the center of the diagram.
+        *text*    `.Text` instance for the diagram label.
+        *texts*   List of `.Text` instances for the flow labels.
+        ========  =============================================================
 
         See Also
         --------