DOC: some debug steps for backend issues

jklymak · jklymak · commit 70ed81909550 · 2023-08-31T14:57:35.000-07:00
diff --git a/doc/users/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst
@@ -77,6 +77,7 @@ environment variable -- see
 directory and the cache directory.
 
 .. _reporting-problems:
+.. _getting-help:
 
 Getting help
 ============
diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst
@@ -248,3 +248,67 @@ 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`.
+
+.. _plots_not_showing:
+
+Debugging 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 (PyCharm),
+please consult their documentation for debugging plots not showing up.
+
+If you are using one of Matplotlib's graphics backends, make sure you know which
+one is being used:
+
+.. code-block:: python3
+   import matplotlib
+
+   print(matplotlib.get_backend())
+
+Try a simple plot, as 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 our of the testing.  Almost all GUI toolkits have a small test
+program that can be run to test basic functionality.  If these fail, try re-installing.
+
+PyQT
+^^^^
+
+.. code-block:: bash
+   python -c "from PyQt5.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()"
+
+or if you have installed `PyQt6`:
+
+.. code-block:: bash
+   python -c "from PyQt6.QtWidgets import *; app = QApplication([]); win = QMainWindow(); win.show(); app.exec()"
+
+GTK
+^^^
+
+.. code-block:: bash
+   python3 -c 'from gi.repository import Gtk; win = Gtk.Window(); win.connect("destroy", Gtk.main_quit); win.show(); Gtk.main()'
+
+wxPython
+^^^^^^^^
+
+.. 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 then contact us (see
+:ref:`getting-help`).
