Minor doc fixes re: close()ing figures.

Most fixes are self-explanatory.  The change to the flask command-line
allows using the same instructions on all OSes.  The one to the
CanvasAgg example is there because it is no longer (since mpl3.1)
necessary to explicitly attach the canvas in the savefig() case.

Author: anntzer

doc/users/faq.rst

@@ -281,7 +281,7 @@ locators as desired because the two axes are independent.
 Generate images without having a window appear
 ----------------------------------------------
 
-The recommended approach since matplotlib 3.1 is to explicitly create a Figure
+The recommended approach since Matplotlib 3.1 is to explicitly create a Figure
 instance::
 
     from matplotlib.figure import Figure
@@ -292,12 +292,10 @@ instance::
 
 This prevents any interaction with GUI frameworks and the window manager.
 
-It's alternatively still possible to use the pyplot interface. Instead of
-calling `matplotlib.pyplot.show`, call `matplotlib.pyplot.savefig`.
-
-Additionally, you must ensure to close the figure after saving it. Not
-closing the figure is a memory leak, because pyplot keeps references
-to all not-yet-shown figures::
+It's alternatively still possible to use the pyplot interface: instead of
+calling `matplotlib.pyplot.show`, call `matplotlib.pyplot.savefig`. In that
+case, you must close the figure after saving it. Not closing the figure causes
+a memory leak, because pyplot keeps references to all not-yet-shown figures. ::
 
     import matplotlib.pyplot as plt
     plt.plot([1, 2, 3])

galleries/examples/user_interfaces/canvasagg.py

@@ -32,10 +32,6 @@
 from matplotlib.figure import Figure
 
 fig = Figure(figsize=(5, 4), dpi=100)
-# A canvas must be manually attached to the figure (pyplot would automatically
-# do it).  This is done by instantiating the canvas with the figure as
-# argument.
-canvas = FigureCanvasAgg(fig)
 
 # Do some plotting.
 ax = fig.add_subplot()
@@ -45,8 +41,12 @@
 # etc.).
 fig.savefig("test.png")
 
-# Option 2: Retrieve a memoryview on the renderer buffer, and convert it to a
+# Option 2 (low-level approach to directly save to a numpy array): Manually
+# attach a canvas to the figure (pyplot or savefig would automatically do
+# it), by instantiating the canvas with the figure as argument; then draw the
+# figure, retrieve a memoryview on the renderer buffer, and convert it to a
 # numpy array.
+canvas = FigureCanvasAgg(fig)
 canvas.draw()
 rgba = np.asarray(canvas.buffer_rgba())
 # ... and pass it to PIL.

galleries/examples/user_interfaces/web_application_server_sgskip.py

@@ -5,7 +5,7 @@
 
 When using Matplotlib in a web server it is strongly recommended to not use
 pyplot (pyplot maintains references to the opened figures to make
-`~.matplotlib.pyplot.show` work, but this will cause memory leaks unless the
+`~.pyplot.show` work, but this will cause memory leaks unless the
 figures are properly closed).
 
 Since Matplotlib 3.1, one can directly create figures using the `.Figure`
@@ -45,21 +45,14 @@ def hello():
 # %%
 #
 # Since the above code is a Flask application, it should be run using the
-# `flask command-line tool <https://flask.palletsprojects.com/en/latest/cli/>`_
-# Assuming that the working directory contains this script:
-#
-# Unix-like systems
+# `flask command-line tool <https://flask.palletsprojects.com/en/latest/cli/>`_:
+# run
 #
 # .. code-block:: console
 #
-#  FLASK_APP=web_application_server_sgskip flask run
-#
-# Windows
-#
-# .. code-block:: console
+#    flask --app web_application_server_sgskip run
 #
-#  set FLASK_APP=web_application_server_sgskip
-#  flask run
+# from the directory containing this script.
 #
 #
 # Clickable images for HTML

lib/matplotlib/pyplot.py

@@ -1263,7 +1263,7 @@ def close(fig: None | int | str | Figure | Literal["all"] = None) -> None:
     -----
     pyplot maintains a reference to figures created with `figure()`. When
     work on the figure is completed, it should be closed, i.e. deregistered
-    from pyplot, to free its memory (see also :rc:figure.max_open_warning).
+    from pyplot, to free its memory (see also :rc:`figure.max_open_warning`).
     Closing a figure window created by `show()` automatically deregisters the
     figure. For all other use cases, most prominently `savefig()` without
     `show()`, the figure must be deregistered explicitly using `close()`.