Backport PR #9942: Minor doc formatting cleanups in pyplot

matplotlib · dstansby · Dec 6, 2017 · Dec 6, 2017 · Dec 6, 2017 · 85811f26ff5460d330893b505ec1c24b7702aab0
commit 85811f26ff5460d330893b505ec1c24b7702aab0
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -1,19 +1,21 @@
 # Note: The first part of this file can be modified in place, but the latter
 # part is autogenerated by the boilerplate.py script.
+
 """
-Provides a MATLAB-like plotting framework.
+`matplotlib.pyplot` is a state-based interface to matplotlib. It provides
+a MATLAB-like way of plotting.

-:mod:`~matplotlib.pylab` combines pyplot with numpy into a single namespace.
-This is convenient for interactive work, but for programming it
-is recommended that the namespaces be kept separate, e.g.::
+pyplot is mainly intended for interactive plots and simple cases of programmatic
+plot generation::

    import numpy as np
    import matplotlib.pyplot as plt

-    x = np.arange(0, 5, 0.1);
+    x = np.arange(0, 5, 0.1)
    y = np.sin(x)
    plt.plot(x, y)

+The object-oriented API is recommended for more complex plots.
 """
 from __future__ import (absolute_import, division, print_function,
                        unicode_literals)
@@ -260,13 +262,13 @@ def isinteractive():


 def ioff():
-    'Turn interactive mode off.'
+    """Turn interactive mode off."""
    matplotlib.interactive(False)
    uninstall_repl_displayhook()


 def ion():
-    'Turn interactive mode on.'
+    """Turn interactive mode on."""
    matplotlib.interactive(True)
    install_repl_displayhook()

@@ -281,6 +283,8 @@ def pause(interval):
    This can be used for crude animation.  For more complex animation, see
    :mod:`matplotlib.animation`.

+    Note
+    ----
    This function is experimental; its behavior may be changed or extended in a
    future release.
    """
@@ -580,8 +584,7 @@ def _auto_draw_if_interactive(fig, val):


 def gcf():
-    "Get a reference to the current figure."
-
+    """Get a reference to the current figure."""
    figManager = _pylab_helpers.Gcf.get_active()
    if figManager is not None:
        return figManager.canvas.figure
@@ -599,7 +602,7 @@ def get_fignums():


 def get_figlabels():
-    "Return a list of existing figure labels."
+    """Return a list of existing figure labels."""
    figManagers = _pylab_helpers.Gcf.get_all_fig_managers()
    figManagers.sort(key=lambda m: m.num)
    return [m.canvas.figure.get_label() for m in figManagers]
@@ -629,9 +632,9 @@ def close(*args):

    ``close()`` by itself closes the current figure

-    ``close(h)`` where *h* is a :class:`Figure` instance, closes that figure
+    ``close(fig)`` closes the `~.Figure` instance *fig*

-    ``close(num)`` closes figure number *num*
+    ``close(num)`` closes the figure number *num*

    ``close(name)`` where *name* is a string, closes figure with that label

@@ -827,7 +830,6 @@ def hold(b=None):
 def ishold():
    """
    Return the hold status of the current axes.
-
    """
    return gca()._hold

@@ -1325,8 +1327,8 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
    """
    Automatically adjust subplot parameters to give specified padding.

-    Parameters:
-
+    Parameters
+    ----------
    pad : float
        padding between the figure edge and the edges of subplots, as a fraction of the font-size.
    h_pad, w_pad : float
@@ -1336,8 +1338,8 @@ def tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None):
        (left, bottom, right, top) in the normalized figure
        coordinate that the whole subplots area (including
        labels) will fit into. Default is (0, 0, 1, 1).
-    """

+    """
    fig = gcf()
    fig.tight_layout(pad=pad, h_pad=h_pad, w_pad=w_pad, rect=rect)