Update description of web application server example.

timhoffm · timhoffm · commit bc35b6d5c6b8 · 2020-10-21T01:25:09.000+02:00
diff --git a/doc/faq/howto_faq.rst b/doc/faq/howto_faq.rst
@@ -433,8 +433,8 @@ the desired format::
 
 .. seealso::
 
-    :ref:`howto-webapp` for information about running matplotlib inside
-    of a web application.
+    :doc:`/gallery/user_interfaces/web_application_server_sgskip` for
+    information about running matplotlib inside of a web application.
 
 .. _howto-show:
 
diff --git a/examples/user_interfaces/web_application_server_sgskip.py b/examples/user_interfaces/web_application_server_sgskip.py
@@ -1,19 +1,21 @@
 """
-.. _howto-webapp:
+=============================================
+Embedding in a web application server (Flask)
+=============================================
 
-=================================================
-How to use Matplotlib in a web application server
-=================================================
+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
+figures are properly closed).
 
-In general, the simplest solution when using Matplotlib in a web server is
-to completely avoid using pyplot (pyplot maintains references to the opened
-figures to make `~.matplotlib.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` constructor and save them to
-in-memory buffers.  The following example uses Flask_, but other frameworks
-work similarly:
+Since Matplotlib 3.1, one can directly create figures using the `.Figure`
+constructor and save them to in-memory buffers.  In older versions, it was
+necessary to explicitly instantiate an Agg canvas (see e.g.
+:doc:`/gallery/user_interfaces/canvasagg`).
 
-.. _Flask: http://flask.pocoo.org/
+The following example uses Flask_, but other frameworks work similarly:
+
+.. _Flask: https://flask.palletsprojects.com
 
 """
 
@@ -39,14 +41,10 @@ def hello():
     data = base64.b64encode(buf.getbuffer()).decode("ascii")
     return f"<img src='data:image/png;base64,{data}'/>"
 
-# %%
-# When using Matplotlib versions older than 3.1, it is necessary to explicitly
-# instantiate an Agg canvas;
-# see e.g. :doc:`/gallery/user_interfaces/canvasagg`.
+#############################################################################
 #
-# Note: This script should be run using the
+# Since the above code is a Flask application, it should be run using the
 # `flask command-line tool <https://flask.palletsprojects.com/en/master/cli/>`_
-# since it is a Flask application.
 # Assuming that the working directory contains this script:
 #
 # Unix-like systems
@@ -62,7 +60,6 @@ def hello():
 #  set FLASK_APP=web_application_server_sgskip
 #  flask run
 #
-# .. _howto-click-maps:
 #
 # Clickable images for HTML
 # -------------------------
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -364,8 +364,9 @@ def my_plotter(ax, data1, data2, param_dict):
 # Linux package named ``python-tk`` (or similar).
 #
 # If, however, you want to write graphical user interfaces, or a web
-# application server (:ref:`howto-webapp`), or need a better
-# understanding of what is going on, read on. To make things a little
+# application server
+# (:doc:`/gallery/user_interfaces/web_application_server_sgskip`), or need a
+# better understanding of what is going on, read on. To make things a little
 # more customizable for graphical user interfaces, Matplotlib separates
 # the concept of the renderer (the thing that actually does the drawing)
 # from the canvas (the place where the drawing goes).  The canonical
