Merge pull request matplotlib#15539 from anntzer/backend-docs

Small cleanups to backend docs.

Author: timhoffm

lib/matplotlib/backends/backend_gtk3.py

@@ -51,8 +51,8 @@
 
 
 class TimerGTK3(TimerBase):
-    '''
-    Subclass of :class:`backend_bases.TimerBase` using GTK3 for timer events.
+    """
+    Subclass of `.TimerBase` using GTK3 for timer events.
 
     Attributes
     ----------
@@ -65,8 +65,8 @@ class TimerGTK3(TimerBase):
         Stores list of (func, args) tuples that will be called upon timer
         events. This list can be manipulated directly, or the functions
         `add_callback` and `remove_callback` can be used.
+    """
 
-    '''
     def _timer_start(self):
         # Need to stop it, otherwise we potentially leak a timer id that will
         # never be stopped.

lib/matplotlib/backends/backend_macosx.py

@@ -19,9 +19,9 @@
 
 
 class TimerMac(_macosx.Timer, TimerBase):
-    '''
-    Subclass of :class:`backend_bases.TimerBase` that uses CoreFoundation
-    run loops for timer events.
+    """
+    Subclass of `.TimerBase` that uses CoreFoundation run loops for timer
+    events.
 
     Attributes
     ----------
@@ -34,8 +34,7 @@ class TimerMac(_macosx.Timer, TimerBase):
         Stores list of (func, args) tuples that will be called upon timer
         events. This list can be manipulated directly, or the functions
         `add_callback` and `remove_callback` can be used.
-
-    '''
+    """
     # completely implemented at the C-level (in _macosx.Timer)
 
 

lib/matplotlib/backends/backend_pdf.py

@@ -2399,9 +2399,8 @@ class PdfPages:
 
     Notes
     -----
-    In reality :class:`PdfPages` is a thin wrapper around :class:`PdfFile`, in
-    order to avoid confusion when using :func:`~matplotlib.pyplot.savefig` and
-    forgetting the format argument.
+    In reality `PdfPages` is a thin wrapper around `PdfFile`, in order to avoid
+    confusion when using `~.pyplot.savefig` and forgetting the format argument.
     """
     __slots__ = ('_file', 'keep_empty')
 
@@ -2412,9 +2411,9 @@ def __init__(self, filename, keep_empty=True, metadata=None):
         Parameters
         ----------
         filename : str or path-like or file-like
-            Plots using :meth:`PdfPages.savefig` will be written to a file at
-            this location. The file is opened at once and any older file with
-            the same name is overwritten.
+            Plots using `PdfPages.savefig` will be written to a file at this
+            location. The file is opened at once and any older file with the
+            same name is overwritten.
         keep_empty : bool, optional
             If set to False, then empty pdf files will be deleted automatically
             when closed.
@@ -2462,18 +2461,17 @@ def infodict(self):
 
     def savefig(self, figure=None, **kwargs):
         """
-        Saves a :class:`~matplotlib.figure.Figure` to this file as a new page.
+        Saves a `.Figure` to this file as a new page.
 
-        Any other keyword arguments are passed to
-        :meth:`~matplotlib.figure.Figure.savefig`.
+        Any other keyword arguments are passed to `~.Figure.savefig`.
 
         Parameters
         ----------
-        figure : :class:`~matplotlib.figure.Figure` or int, optional
+        figure : `.Figure` or int, optional
             Specifies what figure is saved to file. If not specified, the
-            active figure is saved. If a :class:`~matplotlib.figure.Figure`
-            instance is provided, this figure is saved. If an int is specified,
-            the figure instance to save is looked up by number.
+            active figure is saved. If a `.Figure` instance is provided, this
+            figure is saved. If an int is specified, the figure instance to
+            save is looked up by number.
         """
         if not isinstance(figure, Figure):
             if figure is None:

lib/matplotlib/backends/backend_pgf.py

@@ -1017,8 +1017,8 @@ def __init__(self, filename, *, keep_empty=True, metadata=None):
         Parameters
         ----------
         filename : str or path-like
-            Plots using :meth:`PdfPages.savefig` will be written to a file at
-            this location. Any older file with the same name is overwritten.
+            Plots using `PdfPages.savefig` will be written to a file at this
+            location. Any older file with the same name is overwritten.
         keep_empty : bool, optional
             If set to False, then empty pdf files will be deleted automatically
             when closed.
@@ -1127,18 +1127,17 @@ def _run_latex(self):
 
     def savefig(self, figure=None, **kwargs):
         """
-        Saves a :class:`~matplotlib.figure.Figure` to this file as a new page.
+        Saves a `.Figure` to this file as a new page.
 
-        Any other keyword arguments are passed to
-        :meth:`~matplotlib.figure.Figure.savefig`.
+        Any other keyword arguments are passed to `~.Figure.savefig`.
 
         Parameters
         ----------
-        figure : :class:`~matplotlib.figure.Figure` or int, optional
+        figure : `.Figure` or int, optional
             Specifies what figure is saved to file. If not specified, the
-            active figure is saved. If a :class:`~matplotlib.figure.Figure`
-            instance is provided, this figure is saved. If an int is specified,
-            the figure instance to save is looked up by number.
+            active figure is saved. If a `.Figure` instance is provided, this
+            figure is saved. If an int is specified, the figure instance to
+            save is looked up by number.
         """
         if not isinstance(figure, Figure):
             if figure is None:

lib/matplotlib/backends/backend_qt5.py

@@ -175,8 +175,8 @@ def wrapper(self, *args, **kwargs):
 
 
 class TimerQT(TimerBase):
-    '''
-    Subclass of :class:`backend_bases.TimerBase` that uses Qt timer events.
+    """
+    Subclass of `.TimerBase` that uses Qt timer events.
 
     Attributes
     ----------
@@ -189,8 +189,7 @@ class TimerQT(TimerBase):
         Stores list of (func, args) tuples that will be called upon timer
         events. This list can be manipulated directly, or the functions
         `add_callback` and `remove_callback` can be used.
-
-    '''
+    """
 
     def __init__(self, *args, **kwargs):
         TimerBase.__init__(self, *args, **kwargs)

lib/matplotlib/backends/backend_qt5agg.py

@@ -21,7 +21,8 @@ def __init__(self, figure):
         super().__init__(figure=figure)
 
     def paintEvent(self, event):
-        """Copy the image from the Agg canvas to the qt.drawable.
+        """
+        Copy the image from the Agg canvas to the qt.drawable.
 
         In Qt, all drawing should be done inside of here when a widget is
         shown onscreen.
@@ -78,8 +79,7 @@ def paintEvent(self, event):
         painter.end()
 
     def blit(self, bbox=None):
-        """Blit the region in bbox.
-        """
+        # docstring inherited
         # If bbox is None, blit the entire canvas. Otherwise
         # blit only the area defined by the bbox.
         if bbox is None and self.figure:

lib/matplotlib/backends/backend_wx.py

@@ -100,8 +100,8 @@ def raise_msg_to_str(msg):
 
 
 class TimerWx(TimerBase):
-    '''
-    Subclass of :class:`backend_bases.TimerBase` that uses WxTimer events.
+    """
+    Subclass of `.TimerBase` that uses WxTimer events.
 
     Attributes
     ----------
@@ -114,8 +114,7 @@ class TimerWx(TimerBase):
         Stores list of (func, args) tuples that will be called upon timer
         events. This list can be manipulated directly, or the functions
         `add_callback` and `remove_callback` can be used.
-
-    '''
+    """
 
     def __init__(self, *args, **kwargs):
         if args and isinstance(args[0], wx.EvtHandler):

lib/matplotlib/backends/backend_wxagg.py

@@ -33,10 +33,7 @@ def draw(self, drawDC=None):
         self.gui_repaint(drawDC=drawDC, origin='WXAgg')
 
     def blit(self, bbox=None):
-        """
-        Transfer the region of the agg buffer defined by bbox to the display.
-        If bbox is None, the entire buffer is transferred.
-        """
+        # docstring inherited
         if bbox is None:
             self.bitmap = _convert_agg_to_wx_bitmap(self.get_renderer(), None)
             self.gui_repaint()