DOC: add notes to reference draw methods

tacaswell · tacaswell · commit 22e84f6c6a33 · 2021-02-15T20:25:49.000-05:00
The full artist tree needs to be walked in `draw` to ensure that
deferred work is done.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -2030,7 +2030,14 @@ def release_mouse(self, ax):
             self.mouse_grabber = None
 
     def draw(self, *args, **kwargs):
-        """Render the `.Figure`."""
+        """
+        Render the `.Figure`.
+
+        It is important that this method actually walk the artist tree
+        even if not output is produced because this will trigger
+        deferred work (like computing limits auto-limits and tick
+        values) that users may want access to before saving to disk.
+        """
 
     def draw_idle(self, *args, **kwargs):
         """
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
@@ -2734,6 +2734,7 @@ def draw(self):
         _no_output_draw(self.figure)
         return super().draw()
 
+
 FigureManagerPdf = FigureManagerBase
 
 
diff --git a/lib/matplotlib/backends/backend_svg.py b/lib/matplotlib/backends/backend_svg.py
@@ -1367,6 +1367,7 @@ def draw(self):
         _no_output_draw(self.figure)
         return super().draw()
 
+
 FigureManagerSVG = FigureManagerBase
 
 
diff --git a/lib/matplotlib/backends/backend_template.py b/lib/matplotlib/backends/backend_template.py
@@ -191,7 +191,14 @@ class methods button_press_event, button_release_event,
     """
 
     def draw(self):
-        """Draw the figure using the renderer."""
+        """
+        Draw the figure using the renderer.
+
+        It is important that this method actually walk the artist tree
+        even if not output is produced because this will trigger
+        deferred work (like computing limits auto-limits and tick
+        values) that users may want access to before saving to disk.
+        """
         renderer = RendererTemplate(self.figure.dpi)
         self.figure.draw(renderer)
 
