Remove "Use show()" from how-to and move relevant content to show() doscstring

timhoffm · timhoffm · commit 202a5f9253a6 · 2021-04-05T00:53:08.000+02:00
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -436,64 +436,6 @@ the desired format::
     :doc:`/gallery/user_interfaces/web_application_server_sgskip` for
     information about running matplotlib inside of a web application.
 
-.. _howto-show:
-
-Use :func:`~matplotlib.pyplot.show`
------------------------------------
-
-When you want to view your plots on your display,
-the user interface backend will need to start the GUI mainloop.
-This is what :func:`~matplotlib.pyplot.show` does.  It tells
-Matplotlib to raise all of the figure windows created so far and start
-the mainloop. Because this mainloop is blocking by default (i.e., script
-execution is paused), you should only call this once per script, at the end.
-Script execution is resumed after the last window is closed. Therefore, if
-you are using Matplotlib to generate only images and do not want a user
-interface window, you do not need to call ``show`` (see :ref:`howto-batch`
-and :ref:`what-is-a-backend`).
-
-.. note::
-   Because closing a figure window unregisters it from pyplot, you must call
-   `~matplotlib.pyplot.savefig` *before* calling ``show`` if you wish to save
-   the figure as well as view it.
-
-Whether ``show`` blocks further execution of the script or the python
-interpreter depends on whether Matplotlib is set to use interactive mode.
-In non-interactive mode (the default setting), execution is paused
-until the last figure window is closed.  In interactive mode, the execution
-is not paused, which allows you to create additional figures (but the script
-won't finish until the last figure window is closed).
-
-Because it is expensive to draw, you typically will not want Matplotlib
-to redraw a figure many times in a script such as the following::
-
-    plot([1, 2, 3])          # draw here?
-    xlabel('time')           # and here?
-    ylabel('volts')          # and here?
-    title('a simple plot')   # and here?
-    show()
-
-However, it is *possible* to force Matplotlib to draw after every command,
-which might be what you want when working interactively at the
-python console (see :ref:`mpl-shell`), but in a script you want to
-defer all drawing until the call to ``show``.  This is especially
-important for complex figures that take some time to draw.
-:func:`~matplotlib.pyplot.show` is designed to tell Matplotlib that
-you're all done issuing commands and you want to draw the figure now.
-
-.. note::
-
-    :func:`~matplotlib.pyplot.show` should typically only be called at
-    most once per script and it should be the last line of your
-    script.  At that point, the GUI takes control of the interpreter.
-    If you want to force a figure draw, use
-    :func:`~matplotlib.pyplot.draw` instead.
-
-.. versionadded:: v1.0.0
-   Matplotlib 1.0.0 and 1.0.1 added support for calling ``show`` multiple times
-   per script, and harmonized the behavior of interactive mode, across most
-   backends.
-
 .. _how-to-threads:
 
 Working with threads
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -315,29 +315,45 @@ def show(*args, **kwargs):
     """
     Display all open figures.
 
-    In non-interactive mode, *block* defaults to True.  All figures
-    will display and show will not return until all windows are closed.
-    If there are no figures, return immediately.
-
-    In interactive mode *block* defaults to False.  This will ensure
-    that all of the figures are shown and this function immediately returns.
-
     Parameters
     ----------
     block : bool, optional
+        Whether to wait for all figures to be closed before returning.
 
-        If `True` block and run the GUI main loop until all windows
+        If `True` block and run the GUI main loop until all figure windows
         are closed.
 
-        If `False` ensure that all windows are displayed and return
+        If `False` ensure that all figure windows are displayed and return
         immediately.  In this case, you are responsible for ensuring
         that the event loop is running to have responsive figures.
 
+        Defaults to True in non-interactive mode and to False in interactive
+        mode (see `.pyplot.isinteractive`).
+
     See Also
     --------
-    ion : enable interactive mode
-    ioff : disable interactive mode
+    ion : Enable interactive mode, which shows / updates the figure after
+          every plotting command, so that calling ``show()`` is not necessary.
+    ioff : Disable interactive mode.
+    savefig : Save the figure to an image file instead of showing it on screen.
+
+    Notes
+    -----
+    **Saving figures to file and showing a window at the same time**
+
+    If you want an image file as well as a user interface window, use
+    `.pyplot.savefig` before `.pyplot.show`. At the end of (a blocking)
+    ``show()`` the figure is closed and thus unregistered from pyplot. Calling
+    `.pyplot.savefig` afterwards would save a new and thus empty figure. This
+    limitation of command order does not apply if the show is non-blocking or
+    if you keep a reference to the figure and use `.Figure.savefig`.
+
+    **Auto-show in jupyter notebooks**
 
+    The jupyter backends (activated via ``%matplotlib inline``,
+    ``%matplotlib notebook``, or ``%matplotlib widget``), call ``show()`` at
+    the end of every cell by default. Thus, you usually don't have to call it
+    explicitly there.
     """
     _warn_if_gui_out_of_main_thread()
     return _backend_mod.show(*args, **kwargs)
