From 823d60d0d75dac4cc2f3866a8177d5849f04f0b8 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 31 Aug 2023 14:57:35 -0700 Subject: [PATCH] DOC: some debug steps for backend issues [ci doc] --- doc/users/faq.rst | 8 ++ galleries/users_explain/figure/backends.rst | 106 ++++++++++++++++-- .../users_explain/figure/figure_intro.rst | 6 +- .../users_explain/figure/interactive.rst | 2 +- galleries/users_explain/quick_start.py | 4 +- lib/matplotlib/figure.py | 2 +- 6 files changed, 112 insertions(+), 16 deletions(-) diff --git a/doc/users/faq.rst b/doc/users/faq.rst index 42747c814f94..1ff21d739108 100644 --- a/doc/users/faq.rst +++ b/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 -------- diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst index b769fcc12ba2..41345d46d6ff 100644 --- a/galleries/users_explain/figure/backends.rst +++ b/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 `_ 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 +`_ 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`). diff --git a/galleries/users_explain/figure/figure_intro.rst b/galleries/users_explain/figure/figure_intro.rst index c2a823d815ce..462a3fc848dc 100644 --- a/galleries/users_explain/figure/figure_intro.rst +++ b/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 ` 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 -------------------------------------- diff --git a/galleries/users_explain/figure/interactive.rst b/galleries/users_explain/figure/interactive.rst index 9a4c4956ed6d..6fd908fcac7a 100644 --- a/galleries/users_explain/figure/interactive.rst +++ b/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 ` binding to diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index 16d0165ec7a6..eef9d13a016e 100644 --- a/galleries/users_explain/quick_start.py +++ b/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 ` 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` # ------------------------------ diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index baea9232800f..86a9fdd1387e 100644 --- a/lib/matplotlib/figure.py +++ b/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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy