DOC: some debug steps for backend issues [ci doc]

Author: jklymak

doc/users/faq.rst

@@ -8,6 +8,13 @@
 Frequently Asked Questions
 ==========================
 
+.. _how-do-no-figure:
+
+I don't see a figure window
+---------------------------
+
+Please see :ref:`figures-not-showing`.
+
 .. _how-to-too-many-ticks:
 
 Why do I have so many ticks, and/or why are they out of order?
@@ -301,6 +308,7 @@ you must in that case use a *non-interactive backend* (typically Agg), because
 most GUI backends *require* being run from the main thread as well.
 
 .. _reporting-problems:
+.. _get-help:
 
 Get help
 --------

galleries/users_explain/figure/backends.rst

@@ -11,17 +11,17 @@ Backends
 What is a backend?
 ------------------
 
-A lot of documentation on the website and in the mailing lists refers
-to the "backend" and many new users are confused by this term.
-Matplotlib targets many different use cases and output formats.  Some
-people use Matplotlib interactively from the Python shell and have
-plotting windows pop up when they type commands.  Some people run
-`Jupyter <https://jupyter.org>`_ notebooks and draw inline plots for
-quick data analysis. Others embed Matplotlib into graphical user
-interfaces like PyQt or PyGObject to build rich applications.  Some
-people use Matplotlib in batch scripts to generate postscript images
-from numerical simulations, and still others run web application
-servers to dynamically serve up graphs.
+Backends are used for displaying Matplotlib figures (see :ref:`figure-intro`),
+on the screen, or for writing to files. A lot of documentation on the website
+and in the mailing lists refers to the "backend" and many new users are
+confused by this term. Matplotlib targets many different use cases and output
+formats. Some people use Matplotlib interactively from the Python shell and
+have plotting windows pop up when they type commands. Some people run `Jupyter
+<https://jupyter.org>`_ notebooks and draw inline plots for quick data
+analysis. Others embed Matplotlib into graphical user interfaces like PyQt or
+PyGObject to build rich applications. Some people use Matplotlib in batch
+scripts to generate postscript images from numerical simulations, and still
+others run web application servers to dynamically serve up graphs.
 
 To support all of these use cases, Matplotlib can target different
 outputs, and each of these capabilities is called a backend; the
@@ -248,3 +248,87 @@ backend, use ``module://name.of.the.backend`` as the backend name, e.g.
 ``matplotlib.use('module://name.of.the.backend')``.
 
 Information for backend implementers is available at :ref:`writing_backend_interface`.
+
+.. _figures-not-showing:
+
+Debugging the figure windows not showing
+----------------------------------------
+
+Sometimes things do not work as expected, usually during an install.
+
+If you are using a Notebook or integrated development environment (see :ref:`notebooks-and-ides`),
+please consult their documentation for debugging figures not working in their
+environments.
+
+If you are using one of Matplotlib's graphics backends (see :ref:`standalone-scripts-and-interactive-use`), make sure you know which
+one is being used:
+
+.. code-block:: python3
+
+   import matplotlib
+
+   print(matplotlib.get_backend())
+
+Try a simple plot to see if the GUI opens:
+
+.. code-block:: python3
+
+   import matplotlib
+   import matplotlib.pyplot as plt
+
+   print(matplotlib.get_backend())
+   plt.plot((1, 4, 6))
+   plt.show()
+
+If it does not, you perhaps have an installation problem.  A good step at this
+point is to ensure that your GUI toolkit is installed properly, taking
+Matplotlib out of the testing.  Almost all GUI toolkits have a small test
+program that can be run to test basic functionality.  If this test fails, try re-installing.
+
+QtAgg, QtCairo, Qt5Agg, and Qt5Cairo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Test ``PyQt5``.
+
+If you have ``PySide`` or ``PyQt6`` installed rather than ``PyQt5``, just change the import
+accordingly:
+
+.. code-block:: bash
+
+   python -c "from PyQt5.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()"
+
+
+TkAgg and TkCairo
+^^^^^^^^^^^^^^^^^
+
+Test ``tkinter``:
+
+.. code-block:: bash
+
+   python3 -c "from tkinter import Tk; Tk().mainloop()"
+
+GTK3Agg, GTK4Agg, GTK3Cairo, GTK4Cairo
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Test ``Gtk``:
+
+.. code-block:: bash
+
+   python3 -c "from gi.repository import Gtk; win = Gtk.Window(); win.connect('destroy', Gtk.main_quit); win.show(); Gtk.main()"
+
+wxAgg and wxCairo
+^^^^^^^^^^^^^^^^^
+
+Test ``wx``:
+
+.. code-block:: python3
+
+   import wx
+
+   app = wx.App(False)  # Create a new app, don't redirect stdout/stderr to a window.
+   frame = wx.Frame(None, wx.ID_ANY, "Hello World") # A Frame is a top-level window.
+   frame.Show(True)     # Show the frame.
+   app.MainLoop()
+
+If the test works for your desired backend but you still cannot get Matplotlib to display a figure, then contact us (see
+:ref:`get-help`).

galleries/users_explain/figure/figure_intro.rst

@@ -1,7 +1,7 @@
 
 .. redirect-from:: /users/explain/figure
 
-.. _figure_explanation:
+.. _figure-intro:
 
 +++++++++++++++++++++++
 Introduction to Figures
@@ -36,6 +36,8 @@ We will discuss how to create Figures in more detail below, but first it is
 helpful to understand how to view a Figure.  This varies based on how you are
 using Matplotlib, and what :ref:`Backend <what-is-a-backend>` you are using.
 
+.. _notebooks-and-ides:
+
 Notebooks and IDEs
 ------------------
 
@@ -82,6 +84,8 @@ other than the default "inline" backend, you will likely need to use an ipython
 
    %matplotlib notebook
 
+.. _standalone-scripts-and-interactive-use:
+
 Standalone scripts and interactive use
 --------------------------------------
 

galleries/users_explain/figure/interactive.rst

@@ -15,7 +15,7 @@ mouse-location tools built into the Matplotlib GUI windows are often sufficient,
 you can also use the event system to build customized data exploration tools.
 
 .. seealso::
-    :ref:`figure_explanation`.
+    :ref:`figure-intro`.
 
 
 Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to

galleries/users_explain/quick_start.py

@@ -38,7 +38,7 @@
 #
 # Note that to get this Figure to display, you may have to call ``plt.show()``,
 # depending on your backend.  For more details of Figures and backends, see
-# :ref:`figure_explanation`.
+# :ref:`figure-intro`.
 #
 # .. _figure_parts:
 #
@@ -71,7 +71,7 @@
 # :ref:`Matplotlib backends <backends>` support zooming and
 # panning on figure windows.
 #
-# For more on Figures, see :ref:`figure_explanation`.
+# For more on Figures, see :ref:`figure-intro`.
 #
 # :class:`~matplotlib.axes.Axes`
 # ------------------------------

lib/matplotlib/figure.py

@@ -24,7 +24,7 @@
 Some situations call for directly instantiating a `~.figure.Figure` class,
 usually inside an application of some sort (see :ref:`user_interfaces` for a
 list of examples) .  More information about Figures can be found at
-:ref:`figure_explanation`.
+:ref:`figure-intro`.
 """
 
 from contextlib import ExitStack