From 49e6b9e2d7e1231754404020ebea78f901f03a31 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Thu, 23 Feb 2023 17:57:38 -0800 Subject: [PATCH 01/23] DOC: make users/explain a sphinx gallery [ci doc] --- .circleci/config.yml | 3 +++ doc/Makefile | 1 + doc/conf.py | 10 +++++++--- .../users_explain}/api_interfaces.rst | 0 .../explain => galleries/users_explain}/backends.rst | 0 .../users_explain}/event_handling.rst | 0 .../explain => galleries/users_explain}/figures.rst | 0 .../explain => galleries/users_explain}/fonts.rst | 0 .../explain => galleries/users_explain}/index.rst | 0 .../users_explain}/interactive.rst | 0 .../users_explain}/interactive_guide.rst | 0 .../users_explain}/performance.rst | 0 .../writing_a_backend_pyplot_interface.rst | 0 13 files changed, 11 insertions(+), 3 deletions(-) rename {doc/users/explain => galleries/users_explain}/api_interfaces.rst (100%) rename {doc/users/explain => galleries/users_explain}/backends.rst (100%) rename {doc/users/explain => galleries/users_explain}/event_handling.rst (100%) rename {doc/users/explain => galleries/users_explain}/figures.rst (100%) rename {doc/users/explain => galleries/users_explain}/fonts.rst (100%) rename {doc/users/explain => galleries/users_explain}/index.rst (100%) rename {doc/users/explain => galleries/users_explain}/interactive.rst (100%) rename {doc/users/explain => galleries/users_explain}/interactive_guide.rst (100%) rename {doc/users/explain => galleries/users_explain}/performance.rst (100%) rename {doc/users/explain => galleries/users_explain}/writing_a_backend_pyplot_interface.rst (100%) diff --git a/.circleci/config.yml b/.circleci/config.yml index d4fecc8a5394..440c3f0e637b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -97,9 +97,12 @@ commands: - run: name: Install Python dependencies command: | + # remove when sphinx-gallery releases #1071: python -m pip install --user \ numpy<< parameters.numpy_version >> codecov coverage \ -r requirements/doc/doc-requirements.txt + python -m pip install --no-deps --user \ + git+https://github.com/sphinx-gallery/sphinx-gallery.git python -m pip install --no-deps --user \ git+https://github.com/matplotlib/mpl-sphinx-theme.git diff --git a/doc/Makefile b/doc/Makefile index c2534ed043e8..53b7c02b68fa 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -22,6 +22,7 @@ clean: rm -rf "$(SOURCEDIR)/gallery" rm -rf "$(SOURCEDIR)/plot_types" rm -rf "$(SOURCEDIR)/tutorials" + rm -rf "$(SOURCEDIR)/users/explain" rm -rf "$(SOURCEDIR)/savefig" rm -rf "$(SOURCEDIR)/sphinxext/__pycache__" rm -f $(SOURCEDIR)/_static/constrained_layout*.png diff --git a/doc/conf.py b/doc/conf.py index dfb6b6395089..b550dc9c89ef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -213,11 +213,14 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, gallery_conf['image_srcset'] = [] return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs) -gallery_dirs = [f'{ed}' for ed in ['gallery', 'tutorials', 'plot_types'] +gallery_dirs = [f'{ed}' for ed in + ['gallery', 'tutorials', 'plot_types', 'users/explain'] if f'{ed}/*' not in skip_subdirs] -example_dirs = [f'../galleries/{gd}'.replace('gallery', 'examples') - for gd in gallery_dirs] +example_dirs = [] +for gd in gallery_dirs: + gd = gd.replace('gallery', 'examples').replace('users/explain', 'users_explain') + example_dirs += [f'../galleries/{gd}'] sphinx_gallery_conf = { 'backreferences_dir': Path('api') / Path('_as_gen'), @@ -244,6 +247,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, 'thumbnail_size': (320, 224), 'within_subsection_order': gallery_order.subsectionorder, 'capture_repr': (), + 'copyfile_regex': r'.*\.rst', } if 'plot_gallery=0' in sys.argv: diff --git a/doc/users/explain/api_interfaces.rst b/galleries/users_explain/api_interfaces.rst similarity index 100% rename from doc/users/explain/api_interfaces.rst rename to galleries/users_explain/api_interfaces.rst diff --git a/doc/users/explain/backends.rst b/galleries/users_explain/backends.rst similarity index 100% rename from doc/users/explain/backends.rst rename to galleries/users_explain/backends.rst diff --git a/doc/users/explain/event_handling.rst b/galleries/users_explain/event_handling.rst similarity index 100% rename from doc/users/explain/event_handling.rst rename to galleries/users_explain/event_handling.rst diff --git a/doc/users/explain/figures.rst b/galleries/users_explain/figures.rst similarity index 100% rename from doc/users/explain/figures.rst rename to galleries/users_explain/figures.rst diff --git a/doc/users/explain/fonts.rst b/galleries/users_explain/fonts.rst similarity index 100% rename from doc/users/explain/fonts.rst rename to galleries/users_explain/fonts.rst diff --git a/doc/users/explain/index.rst b/galleries/users_explain/index.rst similarity index 100% rename from doc/users/explain/index.rst rename to galleries/users_explain/index.rst diff --git a/doc/users/explain/interactive.rst b/galleries/users_explain/interactive.rst similarity index 100% rename from doc/users/explain/interactive.rst rename to galleries/users_explain/interactive.rst diff --git a/doc/users/explain/interactive_guide.rst b/galleries/users_explain/interactive_guide.rst similarity index 100% rename from doc/users/explain/interactive_guide.rst rename to galleries/users_explain/interactive_guide.rst diff --git a/doc/users/explain/performance.rst b/galleries/users_explain/performance.rst similarity index 100% rename from doc/users/explain/performance.rst rename to galleries/users_explain/performance.rst diff --git a/doc/users/explain/writing_a_backend_pyplot_interface.rst b/galleries/users_explain/writing_a_backend_pyplot_interface.rst similarity index 100% rename from doc/users/explain/writing_a_backend_pyplot_interface.rst rename to galleries/users_explain/writing_a_backend_pyplot_interface.rst From 6a9dff8eb4f5b11c48e695da151e77956299f295 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 3 Mar 2023 16:21:07 -0800 Subject: [PATCH 02/23] DOC: quic_start and figure changes --- galleries/users_explain/backends.rst | 3 +- .../{ => figure}/api_interfaces.rst | 0 .../writing_a_backend_pyplot_interface.rst | 4 + galleries/users_explain/figures.rst | 251 ---------- galleries/users_explain/index.rst | 7 +- galleries/users_explain/interactive.rst | 307 ------------ galleries/users_explain/interactive_guide.rst | 446 ------------------ .../quick_start.py | 1 + 8 files changed, 8 insertions(+), 1011 deletions(-) rename galleries/users_explain/{ => figure}/api_interfaces.rst (100%) rename galleries/users_explain/{ => figure}/writing_a_backend_pyplot_interface.rst (97%) delete mode 100644 galleries/users_explain/figures.rst delete mode 100644 galleries/users_explain/interactive.rst delete mode 100644 galleries/users_explain/interactive_guide.rst rename galleries/{tutorials/introductory => users_explain}/quick_start.py (99%) diff --git a/galleries/users_explain/backends.rst b/galleries/users_explain/backends.rst index 9b188048de50..35be449d050e 100644 --- a/galleries/users_explain/backends.rst +++ b/galleries/users_explain/backends.rst @@ -238,5 +238,4 @@ methods above. If ``name.of.the.backend`` is the module containing the 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 -:doc:`/users/explain/writing_a_backend_pyplot_interface`. +Information for backend implementers is available at :ref:`writing_backend_interface`. \ No newline at end of file diff --git a/galleries/users_explain/api_interfaces.rst b/galleries/users_explain/figure/api_interfaces.rst similarity index 100% rename from galleries/users_explain/api_interfaces.rst rename to galleries/users_explain/figure/api_interfaces.rst diff --git a/galleries/users_explain/writing_a_backend_pyplot_interface.rst b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst similarity index 97% rename from galleries/users_explain/writing_a_backend_pyplot_interface.rst rename to galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst index e193135f970d..356bef65ec95 100644 --- a/galleries/users_explain/writing_a_backend_pyplot_interface.rst +++ b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst @@ -1,3 +1,7 @@ +.. redirect-from:: /users/explain/writing_a_backend_pyplot_interface + +.. _writing_backend_interface: + ========================================= Writing a backend -- the pyplot interface ========================================= diff --git a/galleries/users_explain/figures.rst b/galleries/users_explain/figures.rst deleted file mode 100644 index 4add236f370c..000000000000 --- a/galleries/users_explain/figures.rst +++ /dev/null @@ -1,251 +0,0 @@ - -.. _figure_explanation: - -================================================ -Creating, viewing, and saving Matplotlib Figures -================================================ - -.. plot:: - :include-source: - - fig = plt.figure(figsize=(2, 2), facecolor='lightskyblue', - layout='constrained') - fig.suptitle('Figure') - ax = fig.add_subplot() - ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium') - -When looking at Matplotlib visualization, you are almost always looking at -Artists placed on a `~.Figure`. In the example above, the figure is the -blue region and `~.Figure.add_subplot` has added an `~.axes.Axes` artist to the -`~.Figure` (see :ref:`figure_parts`). A more complicated visualization can add -multiple Axes to the Figure, colorbars, legends, annotations, and the Axes -themselves can have multiple Artists added to them -(e.g. ``ax.plot`` or ``ax.imshow``). - -.. _viewing_figures: - -Viewing Figures -================ - -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 ------------------- - -.. figure:: /_static/FigureInline.png - :alt: Image of figure generated in Jupyter Notebook with inline backend. - :width: 400 - - Screenshot of a `Jupyter Notebook `_, with a figure - generated via the default `inline - `_ backend. - -If you are using a Notebook (e.g. `Jupyter `_) or an IDE -that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that -will render the Matplotlib Figure when a code cell is executed. One thing to -be aware of is that the default Jupyter backend (``%matplotlib inline``) will -by default trim or expand the figure size to have a tight box around Artists -added to the Figure (see :ref:`saving_figures`, below). If you use a backend -other than the default "inline" backend, you will likely need to use an ipython -"magic" like ``%matplotlib notebook`` for the Matplotlib :ref:`notebook -` or ``%matplotlib widget`` for the `ipympl -`_ backend. - -.. figure:: /_static/FigureNotebook.png - :alt: Image of figure generated in Jupyter Notebook with notebook - backend, including a toolbar. - :width: 400 - - Screenshot of a Jupyter Notebook with an interactive figure generated via - the ``%matplotlib notebook`` magic. Users should also try the similar - `widget `_ backend if using `JupyterLab - `_. - - -.. seealso:: - :ref:`interactive_figures`. - -Standalone scripts and interactive use --------------------------------------- - -If the user is on a client with a windowing system, there are a number of -:ref:`Backends ` that can be used to render the Figure to -the screen, usually using a Python Qt, Tk, or Wx toolkit, or the native MacOS -backend. These are typically chosen either in the user's :ref:`matplotlibrc -`, or by calling, for example, -``matplotlib.use('QtAgg')`` at the beginning of a session or script. - -.. figure:: /_static/FigureQtAgg.png - :alt: Image of figure generated from a script via the QtAgg backend. - :width: 370 - - Screenshot of a Figure generated via a python script and shown using the - QtAgg backend. - -When run from a script, or interactively (e.g. from an -`iPython shell `_) the Figure -will not be shown until we call ``plt.show()``. The Figure will appear in -a new GUI window, and usually will have a toolbar with Zoom, Pan, and other tools -for interacting with the Figure. By default, ``plt.show()`` blocks -further interaction from the script or shell until the Figure window is closed, -though that can be toggled off for some purposes. For more details, please see -:ref:`controlling-interactive`. - -Note that if you are on a client that does not have access to a windowing -system, the Figure will fallback to being drawn using the "Agg" backend, and -cannot be viewed, though it can be :ref:`saved `. - -.. seealso:: - :ref:`interactive_figures`. - -.. _creating_figures: - -Creating Figures -================ - -By far the most common way to create a figure is using the -:doc:`pyplot ` interface. As noted in -:ref:`api_interfaces`, the pyplot interface serves two purposes. One is to spin -up the Backend and keep track of GUI windows. The other is a global state for -Axes and Artists that allow a short-form API to plotting methods. In the -example above, we use pyplot for the first purpose, and create the Figure object, -``fig``. As a side effect ``fig`` is also added to pyplot's global state, and -can be accessed via `~.pyplot.gcf`. - -Users typically want an Axes or a grid of Axes when they create a Figure, so in -addition to `~.pyplot.figure`, there are convenience methods that return both -a Figure and some Axes. A simple grid of Axes can be achieved with -`.pyplot.subplots` (which -simply wraps `.Figure.subplots`): - -.. plot:: - :include-source: - - fig, axs = plt.subplots(2, 2, figsize=(4, 3), layout='constrained') - -More complex grids can be achieved with `.pyplot.subplot_mosaic` (which wraps -`.Figure.subplot_mosaic`): - -.. plot:: - :include-source: - - fig, axs = plt.subplot_mosaic([['A', 'right'], ['B', 'right']], - figsize=(4, 3), layout='constrained') - for ax_name in axs: - axs[ax_name].text(0.5, 0.5, ax_name, ha='center', va='center') - -Sometimes we want to have a nested layout in a Figure, with two or more sets of -Axes that do not share the same subplot grid. -We can use `~.Figure.add_subfigure` or `~.Figure.subfigures` to create virtual -figures inside a parent Figure; see -:doc:`/gallery/subplots_axes_and_figures/subfigures` for more details. - -.. plot:: - :include-source: - - fig = plt.figure(layout='constrained', facecolor='lightskyblue') - fig.suptitle('Figure') - figL, figR = fig.subfigures(1, 2) - figL.set_facecolor('thistle') - axL = figL.subplots(2, 1, sharex=True) - axL[1].set_xlabel('x [m]') - figL.suptitle('Left subfigure') - figR.set_facecolor('paleturquoise') - axR = figR.subplots(1, 2, sharey=True) - axR[0].set_title('Axes 1') - figR.suptitle('Right subfigure') - -It is possible to directly instantiate a `.Figure` instance without using the -pyplot interface. This is usually only necessary if you want to create your -own GUI application or service that you do not want carrying the pyplot global -state. See the embedding examples in :ref:`user_interfaces` for examples of -how to do this. - -Figure options --------------- - -There are a few options available when creating figures. The Figure size on -the screen is set by *figsize* and *dpi*. *figsize* is the ``(width, height)`` -of the Figure in inches (or, if preferred, units of 72 typographic points). *dpi* -are how many pixels per inch the figure will be rendered at. To make your Figures -appear on the screen at the physical size you requested, you should set *dpi* -to the same *dpi* as your graphics system. Note that many graphics systems now use -a "dpi ratio" to specify how many screen pixels are used to represent a graphics -pixel. Matplotlib applies the dpi ratio to the *dpi* passed to the figure to make -it have higher resolution, so you should pass the lower number to the figure. - -The *facecolor*, *edgecolor*, *linewidth*, and *frameon* options all change the appearance of the -figure in expected ways, with *frameon* making the figure transparent if set to *False*. - -Finally, the user can specify a layout engine for the figure with the *layout* -parameter. Currently Matplotlib supplies -:doc:`"constrained" `, -:ref:`"compressed" ` and -:doc:`"tight" ` layout engines. These -rescale axes inside the Figure to prevent overlap of ticklabels, and try and align -axes, and can save significant manual adjustment of artists on a Figure for many -common cases. - -Adding Artists --------------- - -The `~.FigureBase` class has a number of methods to add artists to a `~.Figure` or -a `~.SubFigure`. By far the most common are to add Axes of various configurations -(`~.FigureBase.add_axes`, `~.FigureBase.add_subplot`, `~.FigureBase.subplots`, -`~.FigureBase.subplot_mosaic`) and subfigures (`~.FigureBase.subfigures`). Colorbars -are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar`). -It is also possible to have a Figure-level legend (`~.FigureBase.legend`). -Other Artists include figure-wide labels (`~.FigureBase.suptitle`, -`~.FigureBase.supxlabel`, `~.FigureBase.supylabel`) and text (`~.FigureBase.text`). -Finally, low-level Artists can be added directly using `~.FigureBase.add_artist` -usually with care being taken to use the appropriate transform. Usually these -include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and -represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans`` -which will be in physical units of inches from the bottom left corner of the Figure -(see :doc:`/tutorials/advanced/transforms_tutorial` for more details). - - -.. _saving_figures: - -Saving Figures -============== - -Finally, Figures can be saved to disk using the `~.Figure.savefig` method. -``fig.savefig('MyFigure.png', dpi=200)`` will save a PNG formatted figure to -the file ``MyFigure.png`` in the current directory on disk with 200 dots-per-inch -resolution. Note that the filename can include a relative or absolute path to -any place on the file system. - -Many types of output are supported, including raster formats like PNG, GIF, JPEG, -TIFF and vector formats like PDF, EPS, and SVG. - -By default, the size of the saved Figure is set by the Figure size (in inches) and, for the raster -formats, the *dpi*. If *dpi* is not set, then the *dpi* of the Figure is used. -Note that *dpi* still has meaning for vector formats like PDF if the Figure includes -Artists that have been :doc:`rasterized `; the -*dpi* specified will be the resolution of the rasterized objects. - -It is possible to change the size of the Figure using the *bbox_inches* argument -to savefig. This can be specified manually, again in inches. However, by far -the most common use is ``bbox_inches='tight'``. This option "shrink-wraps", trimming -or expanding as needed, the size of the figure so that it is tight around all the artists -in a figure, with a small pad that can be specified by *pad_inches*, which defaults to -0.1 inches. The dashed box in the plot below shows the portion of the figure that -would be saved if ``bbox_inches='tight'`` were used in savefig. - -.. plot:: - - import matplotlib.pyplot as plt - from matplotlib.patches import FancyBboxPatch - - fig, ax = plt.subplots(figsize=(4, 2), facecolor='lightskyblue') - ax.set_position([0.1, 0.2, 0.8, 0.7]) - ax.set_aspect(1) - bb = ax.get_tightbbox() - bb = bb.padded(10) - fancy = FancyBboxPatch(bb.p0, bb.width, bb.height, fc='none', - ec=(0, 0.0, 0, 0.5), lw=2, linestyle='--', - transform=None, clip_on=False) - ax.add_patch(fancy) diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index d70886dc6878..a5ca1e23f608 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -8,12 +8,9 @@ Explanations .. toctree:: :maxdepth: 2 - api_interfaces.rst - figures.rst + quick_start + figure/index backends.rst - writing_a_backend_pyplot_interface.rst - interactive.rst fonts.rst event_handling.rst performance.rst - interactive_guide.rst diff --git a/galleries/users_explain/interactive.rst b/galleries/users_explain/interactive.rst deleted file mode 100644 index 942b682fb04c..000000000000 --- a/galleries/users_explain/interactive.rst +++ /dev/null @@ -1,307 +0,0 @@ -.. redirect-from:: /users/interactive - -.. currentmodule:: matplotlib - -.. _mpl-shell: -.. _interactive_figures: - -=================== -Interactive figures -=================== - -When working with data, interactivity can be invaluable. The pan/zoom and -mouse-location tools built into the Matplotlib GUI windows are often sufficient, but -you can also use the event system to build customized data exploration tools. - -.. seealso:: - :ref:`figure_explanation`. - - -Matplotlib ships with :ref:`backends ` binding to -several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party -packages provide bindings to `kivy -`__ and `Jupyter Lab -`__. For the figures to be responsive to -mouse, keyboard, and paint events, the GUI event loop needs to be integrated -with an interactive prompt. We recommend using IPython (see :ref:`below `). - -The `.pyplot` module provides functions for explicitly creating figures -that include interactive tools, a toolbar, a tool-tip, and -:ref:`key bindings `: - -`.pyplot.figure` - Creates a new empty `.Figure` or selects an existing figure - -`.pyplot.subplots` - Creates a new `.Figure` and fills it with a grid of `~.axes.Axes` - -`.pyplot` has a notion of "The Current Figure" which can be accessed -through `.pyplot.gcf` and a notion of "The Current Axes" accessed -through `.pyplot.gca`. Almost all of the functions in `.pyplot` pass -through the current `.Figure` / `~.axes.Axes` (or create one) as -appropriate. - -Matplotlib keeps a reference to all of the open figures -created via `pyplot.figure` or `pyplot.subplots` so that the figures will not be garbage -collected. `.Figure`\s can be closed and deregistered from `.pyplot` individually via -`.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``. - - -.. seealso:: - - For more discussion of Matplotlib's event system and integrated event loops: - - - :ref:`interactive_figures_and_eventloops` - - :ref:`event-handling-tutorial` - - -.. _ipython-pylab: - -IPython integration -=================== - -We recommend using IPython for an interactive shell. In addition to -all of its features (improved tab-completion, magics, multiline editing, etc), -it also ensures that the GUI toolkit event loop is properly integrated -with the command line (see :ref:`cp_integration`). - -In this example, we create and modify a figure via an IPython prompt. -The figure displays in a QtAgg GUI window. To configure the integration -and enable :ref:`interactive mode ` use the -``%matplotlib`` magic: - -.. highlight:: ipython - -:: - - In [1]: %matplotlib - Using matplotlib backend: QtAgg - - In [2]: import matplotlib.pyplot as plt - -Create a new figure window: - -:: - - In [3]: fig, ax = plt.subplots() - - -Add a line plot of the data to the window: - -:: - - In [4]: ln, = ax.plot(range(5)) - -Change the color of the line from blue to orange: - -:: - - In [5]: ln.set_color('orange') - -If you wish to disable automatic redrawing of the plot: - -:: - - In [6]: plt.ioff() - -If you wish to re-enable automatic redrawing of the plot: - -:: - - In [7]: plt.ion() - - -In recent versions of ``Matplotlib`` and ``IPython``, it is -sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`. -Using the ``%`` magic is guaranteed to work in all versions of Matplotlib and IPython. - - -.. highlight:: python - -.. _controlling-interactive: - -Interactive mode -================ - - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - pyplot.ion - pyplot.ioff - pyplot.isinteractive - - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - pyplot.show - pyplot.pause - - -Interactive mode controls: - -- whether created figures are automatically shown -- whether changes to artists automatically trigger re-drawing existing figures -- when `.pyplot.show()` returns if given no arguments: immediately, or after all of the figures have been closed - -If in interactive mode: - -- newly created figures will be displayed immediately -- figures will automatically redraw when elements are changed -- `pyplot.show()` displays the figures and immediately returns - -If not in interactive mode: - -- newly created figures and changes to figures are not displayed until - - * `.pyplot.show()` is called - * `.pyplot.pause()` is called - * `.FigureCanvasBase.flush_events()` is called - -- `pyplot.show()` runs the GUI event loop and does not return until all the plot windows are closed - -If you are in non-interactive mode (or created figures while in -non-interactive mode) you may need to explicitly call `.pyplot.show` -to display the windows on your screen. If you only want to run the -GUI event loop for a fixed amount of time, you can use `.pyplot.pause`. -This will block the progress of your code as if you had called -`time.sleep`, ensure the current window is shown and re-drawn if needed, -and run the GUI event loop for the specified period of time. - -The GUI event loop being integrated with your command prompt and -the figures being in interactive mode are independent of each other. -If you try to use `pyplot.ion` without arranging for the event-loop integration, -your figures will appear but will not be interactive while the prompt is waiting for input. -You will not be able to pan/zoom and the figure may not even render -(the window might appear black, transparent, or as a snapshot of the -desktop under it). Conversely, if you configure the event loop -integration, displayed figures will be responsive while waiting for input -at the prompt, regardless of pyplot's "interactive mode". - -No matter what combination of interactive mode setting and event loop integration, -figures will be responsive if you use ``pyplot.show(block=True)``, `.pyplot.pause`, or run -the GUI main loop in some other way. - - -.. warning:: - - Using `.Figure.show` it is possible to display a figure on - the screen without starting the event loop and without being in - interactive mode. This may work (depending on the GUI toolkit) but - will likely result in a non-responsive figure. - -.. _navigation-toolbar: - -Default UI -========== - - -The windows created by :mod:`~.pyplot` have an interactive toolbar with navigation -buttons and a readout of the data values the cursor is pointing at. A number of -helpful keybindings are registered by default. - - -.. _key-event-handling: - -Navigation keyboard shortcuts ------------------------------ - -The following table holds all the default keys, which can be -overwritten by use of your :doc:`matplotlibrc -`. - -================================== =============================== -Command Default key binding and rcParam -================================== =============================== -Home/Reset :rc:`keymap.home` -Back :rc:`keymap.back` -Forward :rc:`keymap.forward` -Pan/Zoom :rc:`keymap.pan` -Zoom-to-rect :rc:`keymap.zoom` -Save :rc:`keymap.save` -Toggle fullscreen :rc:`keymap.fullscreen` -Toggle major grids :rc:`keymap.grid` -Toggle minor grids :rc:`keymap.grid_minor` -Toggle x axis scale (log/linear) :rc:`keymap.xscale` -Toggle y axis scale (log/linear) :rc:`keymap.yscale` -Close Figure :rc:`keymap.quit` -Constrain pan/zoom to x axis hold **x** when panning/zooming with mouse -Constrain pan/zoom to y axis hold **y** when panning/zooming with mouse -Preserve aspect ratio hold **CONTROL** when panning/zooming with mouse -================================== =============================== - - -.. _other-shells: - -Other Python prompts -==================== - -Interactive mode works in the default Python prompt: - - -.. sourcecode:: pycon - - >>> import matplotlib.pyplot as plt - >>> plt.ion() - >>> - -however this does not ensure that the event hook is properly installed -and your figures may not be responsive. Please consult the -documentation of your GUI toolkit for details. - - -.. _jupyter_notebooks_jupyterlab: - -Jupyter Notebooks / JupyterLab ------------------------------- - -.. note:: - - To get the interactive functionality described here, you must be - using an interactive backend. The default backend in notebooks, - the inline backend, is not. `~ipykernel.pylab.backend_inline` - renders the figure once and inserts a static image into the - notebook when the cell is executed. Because the images are static, they - can not be panned / zoomed, take user input, or be updated from other - cells. - -To get interactive figures in the 'classic' notebook or Jupyter lab, -use the `ipympl `__ backend -(must be installed separately) which uses the **ipywidget** framework. -If ``ipympl`` is installed use the magic: - -.. sourcecode:: ipython - - %matplotlib widget - -to select and enable it. - -If you only need to use the classic notebook, you can use - -.. sourcecode:: ipython - - %matplotlib notebook - -which uses the `.backend_nbagg` backend provided by Matplotlib; -however, nbagg does not work in Jupyter Lab. - -GUIs + Jupyter -~~~~~~~~~~~~~~ - -You can also use one of the non-``ipympl`` GUI backends in a Jupyter Notebook. -If you are running your Jupyter kernel locally, the GUI window will spawn on -your desktop adjacent to your web browser. If you run your notebook on a remote server, -the kernel will try to open the GUI window on the remote computer. Unless you have -arranged to forward the xserver back to your desktop, you will not be able to -see or interact with the window. It may also raise an exception. - - - -PyCharm, Spyder, and VSCode ---------------------------- - -Many IDEs have built-in integration with Matplotlib, please consult their -documentation for configuration details. diff --git a/galleries/users_explain/interactive_guide.rst b/galleries/users_explain/interactive_guide.rst deleted file mode 100644 index 9c110967d94a..000000000000 --- a/galleries/users_explain/interactive_guide.rst +++ /dev/null @@ -1,446 +0,0 @@ -.. _interactive_figures_and_eventloops: - -.. redirect-from:: /users/interactive_guide - -.. currentmodule:: matplotlib - - -================================================ -Interactive figures and asynchronous programming -================================================ - -Matplotlib supports rich interactive figures by embedding figures into -a GUI window. The basic interactions of panning and zooming in an -Axes to inspect your data is 'baked in' to Matplotlib. This is -supported by a full mouse and keyboard event handling system that -you can use to build sophisticated interactive graphs. - -This guide is meant to be an introduction to the low-level details of -how Matplotlib integration with a GUI event loop works. For a more -practical introduction to the Matplotlib event API see :ref:`event -handling system `, `Interactive Tutorial -`__, and -`Interactive Applications using Matplotlib -`__. - -Event loops -=========== - -Fundamentally, all user interaction (and networking) is implemented as -an infinite loop waiting for events from the user (via the OS) and -then doing something about it. For example, a minimal Read Evaluate -Print Loop (REPL) is :: - - exec_count = 0 - while True: - inp = input(f"[{exec_count}] > ") # Read - ret = eval(inp) # Evaluate - print(ret) # Print - exec_count += 1 # Loop - - -This is missing many niceties (for example, it exits on the first -exception!), but is representative of the event loops that underlie -all terminals, GUIs, and servers [#f1]_. In general the *Read* step -is waiting on some sort of I/O -- be it user input or the network -- -while the *Evaluate* and *Print* are responsible for interpreting the -input and then **doing** something about it. - -In practice we interact with a framework that provides a mechanism to -register callbacks to be run in response to specific events rather -than directly implement the I/O loop [#f2]_. For example "when the -user clicks on this button, please run this function" or "when the -user hits the 'z' key, please run this other function". This allows -users to write reactive, event-driven, programs without having to -delve into the nitty-gritty [#f3]_ details of I/O. The core event loop -is sometimes referred to as "the main loop" and is typically started, -depending on the library, by methods with names like ``_exec``, -``run``, or ``start``. - - -All GUI frameworks (Qt, Wx, Gtk, tk, OSX, or web) have some method of -capturing user interactions and passing them back to the application -(for example ``Signal`` / ``Slot`` framework in Qt) but the exact -details depend on the toolkit. Matplotlib has a :ref:`backend -` for each GUI toolkit we support which uses the -toolkit API to bridge the toolkit UI events into Matplotlib's :ref:`event -handling system `. You can then use -`.FigureCanvasBase.mpl_connect` to connect your function to -Matplotlib's event handling system. This allows you to directly -interact with your data and write GUI toolkit agnostic user -interfaces. - - -.. _cp_integration: - -Command prompt integration -========================== - -So far, so good. We have the REPL (like the IPython terminal) that -lets us interactively send code to the interpreter and get results -back. We also have the GUI toolkit that runs an event loop waiting -for user input and lets us register functions to be run when that -happens. However, if we want to do both we have a problem: the prompt -and the GUI event loop are both infinite loops that each think *they* -are in charge! In order for both the prompt and the GUI windows to be -responsive we need a method to allow the loops to 'timeshare' : - -1. let the GUI main loop block the python process when you want - interactive windows -2. let the CLI main loop block the python process and intermittently - run the GUI loop -3. fully embed python in the GUI (but this is basically writing a full - application) - -.. _cp_block_the_prompt: - -Blocking the prompt -------------------- - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - pyplot.show - pyplot.pause - - backend_bases.FigureCanvasBase.start_event_loop - backend_bases.FigureCanvasBase.stop_event_loop - - -The simplest "integration" is to start the GUI event loop in -'blocking' mode and take over the CLI. While the GUI event loop is -running you can not enter new commands into the prompt (your terminal -may echo the characters typed into the terminal, but they will not be -sent to the Python interpreter because it is busy running the GUI -event loop), but the figure windows will be responsive. Once the -event loop is stopped (leaving any still open figure windows -non-responsive) you will be able to use the prompt again. Re-starting -the event loop will make any open figure responsive again (and will -process any queued up user interaction). - -To start the event loop until all open figures are closed, use -`.pyplot.show` as :: - - pyplot.show(block=True) - -To start the event loop for a fixed amount of time (in seconds) use -`.pyplot.pause`. - -If you are not using `.pyplot` you can start and stop the event loops -via `.FigureCanvasBase.start_event_loop` and -`.FigureCanvasBase.stop_event_loop`. However, in most contexts where -you would not be using `.pyplot` you are embedding Matplotlib in a -large GUI application and the GUI event loop should already be running -for the application. - -Away from the prompt, this technique can be very useful if you want to -write a script that pauses for user interaction, or displays a figure -between polling for additional data. See :ref:`interactive_scripts` -for more details. - - -Input hook integration ----------------------- - -While running the GUI event loop in a blocking mode or explicitly -handling UI events is useful, we can do better! We really want to be -able to have a usable prompt **and** interactive figure windows. - -We can do this using the 'input hook' feature of the interactive -prompt. This hook is called by the prompt as it waits for the user -to type (even for a fast typist the prompt is mostly waiting for the -human to think and move their fingers). Although the details vary -between prompts the logic is roughly - -1. start to wait for keyboard input -2. start the GUI event loop -3. as soon as the user hits a key, exit the GUI event loop and handle the key -4. repeat - -This gives us the illusion of simultaneously having interactive GUI -windows and an interactive prompt. Most of the time the GUI event -loop is running, but as soon as the user starts typing the prompt -takes over again. - -This time-share technique only allows the event loop to run while -python is otherwise idle and waiting for user input. If you want the -GUI to be responsive during long running code it is necessary to -periodically flush the GUI event queue as described in :ref:`spin_event_loop`. -In this case it is your code, not the REPL, which -is blocking the process so you need to handle the "time-share" manually. -Conversely, a very slow figure draw will block the prompt until it -finishes drawing. - -Full embedding -============== - -It is also possible to go the other direction and fully embed figures -(and a `Python interpreter -`__) in a rich -native application. Matplotlib provides classes for each toolkit -which can be directly embedded in GUI applications (this is how the -built-in windows are implemented!). See :ref:`user_interfaces` for -more details. - - -.. _interactive_scripts : - -Scripts and functions -===================== - - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - backend_bases.FigureCanvasBase.flush_events - backend_bases.FigureCanvasBase.draw_idle - - figure.Figure.ginput - pyplot.ginput - - pyplot.show - pyplot.pause - -There are several use-cases for using interactive figures in scripts: - -- capture user input to steer the script -- progress updates as a long running script progresses -- streaming updates from a data source - -Blocking functions ------------------- - -If you only need to collect points in an Axes you can use -`.Figure.ginput`. However if you have written some custom event -handling or are using `.widgets` you will need to manually run the GUI -event loop using the methods described :ref:`above `. - -You can also use the methods described in :ref:`cp_block_the_prompt` -to suspend run the GUI event loop. Once the loop exits your code will -resume. In general, any place you would use `time.sleep` you can use -`.pyplot.pause` instead with the added benefit of interactive figures. - -For example, if you want to poll for data you could use something like :: - - fig, ax = plt.subplots() - ln, = ax.plot([], []) - - while True: - x, y = get_new_data() - ln.set_data(x, y) - plt.pause(1) - -which would poll for new data and update the figure at 1Hz. - -.. _spin_event_loop: - -Explicitly spinning the event Loop ----------------------------------- - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - backend_bases.FigureCanvasBase.flush_events - backend_bases.FigureCanvasBase.draw_idle - - - -If you have open windows that have pending UI -events (mouse clicks, button presses, or draws) you can explicitly -process those events by calling `.FigureCanvasBase.flush_events`. -This will run the GUI event loop until all UI events currently waiting -have been processed. The exact behavior is backend-dependent but -typically events on all figure are processed and only events waiting -to be processed (not those added during processing) will be handled. - -For example :: - - import time - import matplotlib.pyplot as plt - import numpy as np - plt.ion() - - fig, ax = plt.subplots() - th = np.linspace(0, 2*np.pi, 512) - ax.set_ylim(-1.5, 1.5) - - ln, = ax.plot(th, np.sin(th)) - - def slow_loop(N, ln): - for j in range(N): - time.sleep(.1) # to simulate some work - ln.figure.canvas.flush_events() - - slow_loop(100, ln) - -While this will feel a bit laggy (as we are only processing user input -every 100ms whereas 20-30ms is what feels "responsive") it will -respond. - -If you make changes to the plot and want it re-rendered you will need -to call `~.FigureCanvasBase.draw_idle` to request that the canvas be -re-drawn. This method can be thought of *draw_soon* in analogy to -`asyncio.loop.call_soon`. - -We can add this to our example above as :: - - def slow_loop(N, ln): - for j in range(N): - time.sleep(.1) # to simulate some work - if j % 10: - ln.set_ydata(np.sin(((j // 10) % 5 * th))) - ln.figure.canvas.draw_idle() - - ln.figure.canvas.flush_events() - - slow_loop(100, ln) - - -The more frequently you call `.FigureCanvasBase.flush_events` the more -responsive your figure will feel but at the cost of spending more -resources on the visualization and less on your computation. - - -.. _stale_artists: - -Stale artists -============= - -Artists (as of Matplotlib 1.5) have a **stale** attribute which is -`True` if the internal state of the artist has changed since the last -time it was rendered. By default the stale state is propagated up to -the Artists parents in the draw tree, e.g., if the color of a `.Line2D` -instance is changed, the `~.axes.Axes` and `.Figure` that -contain it will also be marked as "stale". Thus, ``fig.stale`` will -report if any artist in the figure has been modified and is out of sync -with what is displayed on the screen. This is intended to be used to -determine if ``draw_idle`` should be called to schedule a re-rendering -of the figure. - -Each artist has a `.Artist.stale_callback` attribute which holds a callback -with the signature :: - - def callback(self: Artist, val: bool) -> None: - ... - -which by default is set to a function that forwards the stale state to -the artist's parent. If you wish to suppress a given artist from propagating -set this attribute to None. - -`.Figure` instances do not have a containing artist and their -default callback is `None`. If you call `.pyplot.ion` and are not in -``IPython`` we will install a callback to invoke -`~.backend_bases.FigureCanvasBase.draw_idle` whenever the -`.Figure` becomes stale. In ``IPython`` we use the -``'post_execute'`` hook to invoke -`~.backend_bases.FigureCanvasBase.draw_idle` on any stale figures -after having executed the user's input, but before returning the prompt -to the user. If you are not using `.pyplot` you can use the callback -`Figure.stale_callback` attribute to be notified when a figure has -become stale. - - -.. _draw_idle: - -Idle draw -========= - -.. autosummary:: - :template: autosummary.rst - :nosignatures: - - backend_bases.FigureCanvasBase.draw - backend_bases.FigureCanvasBase.draw_idle - backend_bases.FigureCanvasBase.flush_events - - -In almost all cases, we recommend using -`backend_bases.FigureCanvasBase.draw_idle` over -`backend_bases.FigureCanvasBase.draw`. ``draw`` forces a rendering of -the figure whereas ``draw_idle`` schedules a rendering the next time -the GUI window is going to re-paint the screen. This improves -performance by only rendering pixels that will be shown on the screen. If -you want to be sure that the screen is updated as soon as possible do :: - - fig.canvas.draw_idle() - fig.canvas.flush_events() - - - -Threading -========= - -Most GUI frameworks require that all updates to the screen, and hence -their main event loop, run on the main thread. This makes pushing -periodic updates of a plot to a background thread impossible. -Although it seems backwards, it is typically easier to push your -computations to a background thread and periodically update -the figure on the main thread. - -In general Matplotlib is not thread safe. If you are going to update -`.Artist` objects in one thread and draw from another you should make -sure that you are locking in the critical sections. - - - -Eventloop integration mechanism -=============================== - -CPython / readline ------------------- - -The Python C API provides a hook, :c:data:`PyOS_InputHook`, to register a -function to be run ("The function will be called when Python's -interpreter prompt is about to become idle and wait for user input -from the terminal."). This hook can be used to integrate a second -event loop (the GUI event loop) with the python input prompt loop. -The hook functions typically exhaust all pending events on the GUI -event queue, run the main loop for a short fixed amount of time, or -run the event loop until a key is pressed on stdin. - -Matplotlib does not currently do any management of :c:data:`PyOS_InputHook` due -to the wide range of ways that Matplotlib is used. This management is left to -downstream libraries -- either user code or the shell. Interactive figures, -even with Matplotlib in 'interactive mode', may not work in the vanilla python -repl if an appropriate :c:data:`PyOS_InputHook` is not registered. - -Input hooks, and helpers to install them, are usually included with -the python bindings for GUI toolkits and may be registered on import. -IPython also ships input hook functions for all of the GUI frameworks -Matplotlib supports which can be installed via ``%matplotlib``. This -is the recommended method of integrating Matplotlib and a prompt. - - -IPython / prompt_toolkit ------------------------- - -With IPython >= 5.0 IPython has changed from using CPython's readline -based prompt to a ``prompt_toolkit`` based prompt. ``prompt_toolkit`` -has the same conceptual input hook, which is fed into ``prompt_toolkit`` via the -:meth:`IPython.terminal.interactiveshell.TerminalInteractiveShell.inputhook` -method. The source for the ``prompt_toolkit`` input hooks lives at -``IPython.terminal.pt_inputhooks``. - - - -.. rubric:: Footnotes - -.. [#f1] A limitation of this design is that you can only wait for one - input, if there is a need to multiplex between multiple sources - then the loop would look something like :: - - fds = [...] - while True: # Loop - inp = select(fds).read() # Read - eval(inp) # Evaluate / Print - -.. [#f2] Or you can `write your own - `__ if you must. - -.. [#f3] These examples are aggressively dropping many of the - complexities that must be dealt with in the real world such as - keyboard interrupts, timeouts, bad input, resource - allocation and cleanup, etc. diff --git a/galleries/tutorials/introductory/quick_start.py b/galleries/users_explain/quick_start.py similarity index 99% rename from galleries/tutorials/introductory/quick_start.py rename to galleries/users_explain/quick_start.py index 0c34ca639bba..1b597f09a8c4 100644 --- a/galleries/tutorials/introductory/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -7,6 +7,7 @@ help you get started with Matplotlib. .. redirect-from:: /tutorials/introductory/usage +.. redirect-from:: /tutorials/introductory/quick_start """ From c7ad14120f5f3fb34b362ca00ef8ffcd5c29df9b Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 3 Mar 2023 16:21:44 -0800 Subject: [PATCH 03/23] DOC: quic_start and figure changes --- galleries/users_explain/figure/index.rst | 269 +++++++++++ .../users_explain/figure/interactive.rst | 308 ++++++++++++ .../figure/interactive_guide.rst | 446 ++++++++++++++++++ galleries/users_explain/index.rst | 1 + 4 files changed, 1024 insertions(+) create mode 100644 galleries/users_explain/figure/index.rst create mode 100644 galleries/users_explain/figure/interactive.rst create mode 100644 galleries/users_explain/figure/interactive_guide.rst diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst new file mode 100644 index 000000000000..afd38a9723cb --- /dev/null +++ b/galleries/users_explain/figure/index.rst @@ -0,0 +1,269 @@ + +.. redirect_from:: /users/explain/figure +.. _figure_explanation: + ++++++++++++++++++ +Figures ++++++++++++++++++ + +.. plot:: + :include-source: + + fig = plt.figure(figsize=(2, 2), facecolor='lightskyblue', + layout='constrained') + fig.suptitle('Figure') + ax = fig.add_subplot() + ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium') + +When looking at Matplotlib visualization, you are almost always looking at +Artists placed on a `~.Figure`. In the example above, the figure is the +blue region and `~.Figure.add_subplot` has added an `~.axes.Axes` artist to the +`~.Figure` (see :ref:`figure_parts`). A more complicated visualization can add +multiple Axes to the Figure, colorbars, legends, annotations, and the Axes +themselves can have multiple Artists added to them +(e.g. ``ax.plot`` or ``ax.imshow``). + +.. contents:: :local: + + +.. _viewing_figures: + +Viewing Figures +================ + +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 +------------------ + +.. figure:: /_static/FigureInline.png + :alt: Image of figure generated in Jupyter Notebook with inline backend. + :width: 400 + + Screenshot of a `Jupyter Notebook `_, with a figure + generated via the default `inline + `_ backend. + + +If you are using a Notebook (e.g. `Jupyter `_) or an IDE +that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that +will render the Matplotlib Figure when a code cell is executed. One thing to +be aware of is that the default Jupyter backend (``%matplotlib inline``) will +by default trim or expand the figure size to have a tight box around Artists +added to the Figure (see :ref:`saving_figures`, below). If you use a backend +other than the default "inline" backend, you will likely need to use an ipython +"magic" like ``%matplotlib notebook`` for the Matplotlib :ref:`notebook +` or ``%matplotlib widget`` for the `ipympl +`_ backend. + +.. figure:: /_static/FigureNotebook.png + :alt: Image of figure generated in Jupyter Notebook with notebook + backend, including a toolbar. + :width: 400 + + Screenshot of a Jupyter Notebook with an interactive figure generated via + the ``%matplotlib notebook`` magic. Users should also try the similar + `widget `_ backend if using `JupyterLab + `_. + + +.. seealso:: + :ref:`interactive_figures`. + +Standalone scripts and interactive use +-------------------------------------- + +If the user is on a client with a windowing system, there are a number of +:ref:`Backends ` that can be used to render the Figure to +the screen, usually using a Python Qt, Tk, or Wx toolkit, or the native MacOS +backend. These are typically chosen either in the user's :ref:`matplotlibrc +`, or by calling, for example, +``matplotlib.use('QtAgg')`` at the beginning of a session or script. + +.. figure:: /_static/FigureQtAgg.png + :alt: Image of figure generated from a script via the QtAgg backend. + :width: 370 + + Screenshot of a Figure generated via a python script and shown using the + QtAgg backend. + +When run from a script, or interactively (e.g. from an +`iPython shell `_) the Figure +will not be shown until we call ``plt.show()``. The Figure will appear in +a new GUI window, and usually will have a toolbar with Zoom, Pan, and other tools +for interacting with the Figure. By default, ``plt.show()`` blocks +further interaction from the script or shell until the Figure window is closed, +though that can be toggled off for some purposes. For more details, please see +:ref:`controlling-interactive`. + +Note that if you are on a client that does not have access to a windowing +system, the Figure will fallback to being drawn using the "Agg" backend, and +cannot be viewed, though it can be :ref:`saved `. + +.. seealso:: + :ref:`interactive_figures`. + +.. _creating_figures: + +Creating Figures +================ + +By far the most common way to create a figure is using the +:doc:`pyplot ` interface. As noted in +:ref:`api_interfaces`, the pyplot interface serves two purposes. One is to spin +up the Backend and keep track of GUI windows. The other is a global state for +Axes and Artists that allow a short-form API to plotting methods. In the +example above, we use pyplot for the first purpose, and create the Figure object, +``fig``. As a side effect ``fig`` is also added to pyplot's global state, and +can be accessed via `~.pyplot.gcf`. + +Users typically want an Axes or a grid of Axes when they create a Figure, so in +addition to `~.pyplot.figure`, there are convenience methods that return both +a Figure and some Axes. A simple grid of Axes can be achieved with +`.pyplot.subplots` (which +simply wraps `.Figure.subplots`): + +.. plot:: + :include-source: + + fig, axs = plt.subplots(2, 2, figsize=(4, 3), layout='constrained') + +More complex grids can be achieved with `.pyplot.subplot_mosaic` (which wraps +`.Figure.subplot_mosaic`): + +.. plot:: + :include-source: + + fig, axs = plt.subplot_mosaic([['A', 'right'], ['B', 'right']], + figsize=(4, 3), layout='constrained') + for ax_name in axs: + axs[ax_name].text(0.5, 0.5, ax_name, ha='center', va='center') + +Sometimes we want to have a nested layout in a Figure, with two or more sets of +Axes that do not share the same subplot grid. +We can use `~.Figure.add_subfigure` or `~.Figure.subfigures` to create virtual +figures inside a parent Figure; see +:doc:`/gallery/subplots_axes_and_figures/subfigures` for more details. + +.. plot:: + :include-source: + + fig = plt.figure(layout='constrained', facecolor='lightskyblue') + fig.suptitle('Figure') + figL, figR = fig.subfigures(1, 2) + figL.set_facecolor('thistle') + axL = figL.subplots(2, 1, sharex=True) + axL[1].set_xlabel('x [m]') + figL.suptitle('Left subfigure') + figR.set_facecolor('paleturquoise') + axR = figR.subplots(1, 2, sharey=True) + axR[0].set_title('Axes 1') + figR.suptitle('Right subfigure') + +It is possible to directly instantiate a `.Figure` instance without using the +pyplot interface. This is usually only necessary if you want to create your +own GUI application or service that you do not want carrying the pyplot global +state. See the embedding examples in :ref:`user_interfaces` for examples of +how to do this. + +Figure options +-------------- + +There are a few options available when creating figures. The Figure size on +the screen is set by *figsize* and *dpi*. *figsize* is the ``(width, height)`` +of the Figure in inches (or, if preferred, units of 72 typographic points). *dpi* +are how many pixels per inch the figure will be rendered at. To make your Figures +appear on the screen at the physical size you requested, you should set *dpi* +to the same *dpi* as your graphics system. Note that many graphics systems now use +a "dpi ratio" to specify how many screen pixels are used to represent a graphics +pixel. Matplotlib applies the dpi ratio to the *dpi* passed to the figure to make +it have higher resolution, so you should pass the lower number to the figure. + +The *facecolor*, *edgecolor*, *linewidth*, and *frameon* options all change the appearance of the +figure in expected ways, with *frameon* making the figure transparent if set to *False*. + +Finally, the user can specify a layout engine for the figure with the *layout* +parameter. Currently Matplotlib supplies +:doc:`"constrained" `, +:ref:`"compressed" ` and +:doc:`"tight" ` layout engines. These +rescale axes inside the Figure to prevent overlap of ticklabels, and try and align +axes, and can save significant manual adjustment of artists on a Figure for many +common cases. + +Adding Artists +-------------- + +The `~.FigureBase` class has a number of methods to add artists to a `~.Figure` or +a `~.SubFigure`. By far the most common are to add Axes of various configurations +(`~.FigureBase.add_axes`, `~.FigureBase.add_subplot`, `~.FigureBase.subplots`, +`~.FigureBase.subplot_mosaic`) and subfigures (`~.FigureBase.subfigures`). Colorbars +are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar`). +It is also possible to have a Figure-level legend (`~.FigureBase.legend`). +Other Artists include figure-wide labels (`~.FigureBase.suptitle`, +`~.FigureBase.supxlabel`, `~.FigureBase.supylabel`) and text (`~.FigureBase.text`). +Finally, low-level Artists can be added directly using `~.FigureBase.add_artist` +usually with care being taken to use the appropriate transform. Usually these +include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and +represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans`` +which will be in physical units of inches from the bottom left corner of the Figure +(see :doc:`/tutorials/advanced/transforms_tutorial` for more details). + + +.. _saving_figures: + +Saving Figures +============== + +Finally, Figures can be saved to disk using the `~.Figure.savefig` method. +``fig.savefig('MyFigure.png', dpi=200)`` will save a PNG formatted figure to +the file ``MyFigure.png`` in the current directory on disk with 200 dots-per-inch +resolution. Note that the filename can include a relative or absolute path to +any place on the file system. + +Many types of output are supported, including raster formats like PNG, GIF, JPEG, +TIFF and vector formats like PDF, EPS, and SVG. + +By default, the size of the saved Figure is set by the Figure size (in inches) and, for the raster +formats, the *dpi*. If *dpi* is not set, then the *dpi* of the Figure is used. +Note that *dpi* still has meaning for vector formats like PDF if the Figure includes +Artists that have been :doc:`rasterized `; the +*dpi* specified will be the resolution of the rasterized objects. + +It is possible to change the size of the Figure using the *bbox_inches* argument +to savefig. This can be specified manually, again in inches. However, by far +the most common use is ``bbox_inches='tight'``. This option "shrink-wraps", trimming +or expanding as needed, the size of the figure so that it is tight around all the artists +in a figure, with a small pad that can be specified by *pad_inches*, which defaults to +0.1 inches. The dashed box in the plot below shows the portion of the figure that +would be saved if ``bbox_inches='tight'`` were used in savefig. + +.. plot:: + + import matplotlib.pyplot as plt + from matplotlib.patches import FancyBboxPatch + + fig, ax = plt.subplots(figsize=(4, 2), facecolor='lightskyblue') + ax.set_position([0.1, 0.2, 0.8, 0.7]) + ax.set_aspect(1) + bb = ax.get_tightbbox() + bb = bb.padded(10) + fancy = FancyBboxPatch(bb.p0, bb.width, bb.height, fc='none', + ec=(0, 0.0, 0, 0.5), lw=2, linestyle='--', + transform=None, clip_on=False) + ax.add_patch(fancy) + + +More reading +============ + +.. toctree:: + :maxdepth: 1 + + Concept: Matplotlib Application Interfaces (APIs) + In depth: Interacting with figures + In depth: Interactive figures and asynchronous programming + In depth: Writing a backend -- the pyplot interface + diff --git a/galleries/users_explain/figure/interactive.rst b/galleries/users_explain/figure/interactive.rst new file mode 100644 index 000000000000..a710435886ed --- /dev/null +++ b/galleries/users_explain/figure/interactive.rst @@ -0,0 +1,308 @@ +.. redirect-from:: /users/interactive +.. redirect-from:: /users/explain/interactive + +.. currentmodule:: matplotlib + +.. _mpl-shell: +.. _interactive_figures: + +=================== +Interactive figures +=================== + +When working with data, interactivity can be invaluable. The pan/zoom and +mouse-location tools built into the Matplotlib GUI windows are often sufficient, but +you can also use the event system to build customized data exploration tools. + +.. seealso:: + :ref:`figure_explanation`. + + +Matplotlib ships with :ref:`backends ` binding to +several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party +packages provide bindings to `kivy +`__ and `Jupyter Lab +`__. For the figures to be responsive to +mouse, keyboard, and paint events, the GUI event loop needs to be integrated +with an interactive prompt. We recommend using IPython (see :ref:`below `). + +The `.pyplot` module provides functions for explicitly creating figures +that include interactive tools, a toolbar, a tool-tip, and +:ref:`key bindings `: + +`.pyplot.figure` + Creates a new empty `.Figure` or selects an existing figure + +`.pyplot.subplots` + Creates a new `.Figure` and fills it with a grid of `~.axes.Axes` + +`.pyplot` has a notion of "The Current Figure" which can be accessed +through `.pyplot.gcf` and a notion of "The Current Axes" accessed +through `.pyplot.gca`. Almost all of the functions in `.pyplot` pass +through the current `.Figure` / `~.axes.Axes` (or create one) as +appropriate. + +Matplotlib keeps a reference to all of the open figures +created via `pyplot.figure` or `pyplot.subplots` so that the figures will not be garbage +collected. `.Figure`\s can be closed and deregistered from `.pyplot` individually via +`.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``. + + +.. seealso:: + + For more discussion of Matplotlib's event system and integrated event loops: + + - :ref:`interactive_figures_and_eventloops` + - :ref:`event-handling-tutorial` + + +.. _ipython-pylab: + +IPython integration +=================== + +We recommend using IPython for an interactive shell. In addition to +all of its features (improved tab-completion, magics, multiline editing, etc), +it also ensures that the GUI toolkit event loop is properly integrated +with the command line (see :ref:`cp_integration`). + +In this example, we create and modify a figure via an IPython prompt. +The figure displays in a QtAgg GUI window. To configure the integration +and enable :ref:`interactive mode ` use the +``%matplotlib`` magic: + +.. highlight:: ipython + +:: + + In [1]: %matplotlib + Using matplotlib backend: QtAgg + + In [2]: import matplotlib.pyplot as plt + +Create a new figure window: + +:: + + In [3]: fig, ax = plt.subplots() + + +Add a line plot of the data to the window: + +:: + + In [4]: ln, = ax.plot(range(5)) + +Change the color of the line from blue to orange: + +:: + + In [5]: ln.set_color('orange') + +If you wish to disable automatic redrawing of the plot: + +:: + + In [6]: plt.ioff() + +If you wish to re-enable automatic redrawing of the plot: + +:: + + In [7]: plt.ion() + + +In recent versions of ``Matplotlib`` and ``IPython``, it is +sufficient to import `matplotlib.pyplot` and call `.pyplot.ion`. +Using the ``%`` magic is guaranteed to work in all versions of Matplotlib and IPython. + + +.. highlight:: python + +.. _controlling-interactive: + +Interactive mode +================ + + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + pyplot.ion + pyplot.ioff + pyplot.isinteractive + + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + pyplot.show + pyplot.pause + + +Interactive mode controls: + +- whether created figures are automatically shown +- whether changes to artists automatically trigger re-drawing existing figures +- when `.pyplot.show()` returns if given no arguments: immediately, or after all of the figures have been closed + +If in interactive mode: + +- newly created figures will be displayed immediately +- figures will automatically redraw when elements are changed +- `pyplot.show()` displays the figures and immediately returns + +If not in interactive mode: + +- newly created figures and changes to figures are not displayed until + + * `.pyplot.show()` is called + * `.pyplot.pause()` is called + * `.FigureCanvasBase.flush_events()` is called + +- `pyplot.show()` runs the GUI event loop and does not return until all the plot windows are closed + +If you are in non-interactive mode (or created figures while in +non-interactive mode) you may need to explicitly call `.pyplot.show` +to display the windows on your screen. If you only want to run the +GUI event loop for a fixed amount of time, you can use `.pyplot.pause`. +This will block the progress of your code as if you had called +`time.sleep`, ensure the current window is shown and re-drawn if needed, +and run the GUI event loop for the specified period of time. + +The GUI event loop being integrated with your command prompt and +the figures being in interactive mode are independent of each other. +If you try to use `pyplot.ion` without arranging for the event-loop integration, +your figures will appear but will not be interactive while the prompt is waiting for input. +You will not be able to pan/zoom and the figure may not even render +(the window might appear black, transparent, or as a snapshot of the +desktop under it). Conversely, if you configure the event loop +integration, displayed figures will be responsive while waiting for input +at the prompt, regardless of pyplot's "interactive mode". + +No matter what combination of interactive mode setting and event loop integration, +figures will be responsive if you use ``pyplot.show(block=True)``, `.pyplot.pause`, or run +the GUI main loop in some other way. + + +.. warning:: + + Using `.Figure.show` it is possible to display a figure on + the screen without starting the event loop and without being in + interactive mode. This may work (depending on the GUI toolkit) but + will likely result in a non-responsive figure. + +.. _navigation-toolbar: + +Default UI +========== + + +The windows created by :mod:`~.pyplot` have an interactive toolbar with navigation +buttons and a readout of the data values the cursor is pointing at. A number of +helpful keybindings are registered by default. + + +.. _key-event-handling: + +Navigation keyboard shortcuts +----------------------------- + +The following table holds all the default keys, which can be +overwritten by use of your :doc:`matplotlibrc +`. + +================================== =============================== +Command Default key binding and rcParam +================================== =============================== +Home/Reset :rc:`keymap.home` +Back :rc:`keymap.back` +Forward :rc:`keymap.forward` +Pan/Zoom :rc:`keymap.pan` +Zoom-to-rect :rc:`keymap.zoom` +Save :rc:`keymap.save` +Toggle fullscreen :rc:`keymap.fullscreen` +Toggle major grids :rc:`keymap.grid` +Toggle minor grids :rc:`keymap.grid_minor` +Toggle x axis scale (log/linear) :rc:`keymap.xscale` +Toggle y axis scale (log/linear) :rc:`keymap.yscale` +Close Figure :rc:`keymap.quit` +Constrain pan/zoom to x axis hold **x** when panning/zooming with mouse +Constrain pan/zoom to y axis hold **y** when panning/zooming with mouse +Preserve aspect ratio hold **CONTROL** when panning/zooming with mouse +================================== =============================== + + +.. _other-shells: + +Other Python prompts +==================== + +Interactive mode works in the default Python prompt: + + +.. sourcecode:: pycon + + >>> import matplotlib.pyplot as plt + >>> plt.ion() + >>> + +however this does not ensure that the event hook is properly installed +and your figures may not be responsive. Please consult the +documentation of your GUI toolkit for details. + + +.. _jupyter_notebooks_jupyterlab: + +Jupyter Notebooks / JupyterLab +------------------------------ + +.. note:: + + To get the interactive functionality described here, you must be + using an interactive backend. The default backend in notebooks, + the inline backend, is not. `~ipykernel.pylab.backend_inline` + renders the figure once and inserts a static image into the + notebook when the cell is executed. Because the images are static, they + can not be panned / zoomed, take user input, or be updated from other + cells. + +To get interactive figures in the 'classic' notebook or Jupyter lab, +use the `ipympl `__ backend +(must be installed separately) which uses the **ipywidget** framework. +If ``ipympl`` is installed use the magic: + +.. sourcecode:: ipython + + %matplotlib widget + +to select and enable it. + +If you only need to use the classic notebook, you can use + +.. sourcecode:: ipython + + %matplotlib notebook + +which uses the `.backend_nbagg` backend provided by Matplotlib; +however, nbagg does not work in Jupyter Lab. + +GUIs + Jupyter +~~~~~~~~~~~~~~ + +You can also use one of the non-``ipympl`` GUI backends in a Jupyter Notebook. +If you are running your Jupyter kernel locally, the GUI window will spawn on +your desktop adjacent to your web browser. If you run your notebook on a remote server, +the kernel will try to open the GUI window on the remote computer. Unless you have +arranged to forward the xserver back to your desktop, you will not be able to +see or interact with the window. It may also raise an exception. + + + +PyCharm, Spyder, and VSCode +--------------------------- + +Many IDEs have built-in integration with Matplotlib, please consult their +documentation for configuration details. diff --git a/galleries/users_explain/figure/interactive_guide.rst b/galleries/users_explain/figure/interactive_guide.rst new file mode 100644 index 000000000000..9c110967d94a --- /dev/null +++ b/galleries/users_explain/figure/interactive_guide.rst @@ -0,0 +1,446 @@ +.. _interactive_figures_and_eventloops: + +.. redirect-from:: /users/interactive_guide + +.. currentmodule:: matplotlib + + +================================================ +Interactive figures and asynchronous programming +================================================ + +Matplotlib supports rich interactive figures by embedding figures into +a GUI window. The basic interactions of panning and zooming in an +Axes to inspect your data is 'baked in' to Matplotlib. This is +supported by a full mouse and keyboard event handling system that +you can use to build sophisticated interactive graphs. + +This guide is meant to be an introduction to the low-level details of +how Matplotlib integration with a GUI event loop works. For a more +practical introduction to the Matplotlib event API see :ref:`event +handling system `, `Interactive Tutorial +`__, and +`Interactive Applications using Matplotlib +`__. + +Event loops +=========== + +Fundamentally, all user interaction (and networking) is implemented as +an infinite loop waiting for events from the user (via the OS) and +then doing something about it. For example, a minimal Read Evaluate +Print Loop (REPL) is :: + + exec_count = 0 + while True: + inp = input(f"[{exec_count}] > ") # Read + ret = eval(inp) # Evaluate + print(ret) # Print + exec_count += 1 # Loop + + +This is missing many niceties (for example, it exits on the first +exception!), but is representative of the event loops that underlie +all terminals, GUIs, and servers [#f1]_. In general the *Read* step +is waiting on some sort of I/O -- be it user input or the network -- +while the *Evaluate* and *Print* are responsible for interpreting the +input and then **doing** something about it. + +In practice we interact with a framework that provides a mechanism to +register callbacks to be run in response to specific events rather +than directly implement the I/O loop [#f2]_. For example "when the +user clicks on this button, please run this function" or "when the +user hits the 'z' key, please run this other function". This allows +users to write reactive, event-driven, programs without having to +delve into the nitty-gritty [#f3]_ details of I/O. The core event loop +is sometimes referred to as "the main loop" and is typically started, +depending on the library, by methods with names like ``_exec``, +``run``, or ``start``. + + +All GUI frameworks (Qt, Wx, Gtk, tk, OSX, or web) have some method of +capturing user interactions and passing them back to the application +(for example ``Signal`` / ``Slot`` framework in Qt) but the exact +details depend on the toolkit. Matplotlib has a :ref:`backend +` for each GUI toolkit we support which uses the +toolkit API to bridge the toolkit UI events into Matplotlib's :ref:`event +handling system `. You can then use +`.FigureCanvasBase.mpl_connect` to connect your function to +Matplotlib's event handling system. This allows you to directly +interact with your data and write GUI toolkit agnostic user +interfaces. + + +.. _cp_integration: + +Command prompt integration +========================== + +So far, so good. We have the REPL (like the IPython terminal) that +lets us interactively send code to the interpreter and get results +back. We also have the GUI toolkit that runs an event loop waiting +for user input and lets us register functions to be run when that +happens. However, if we want to do both we have a problem: the prompt +and the GUI event loop are both infinite loops that each think *they* +are in charge! In order for both the prompt and the GUI windows to be +responsive we need a method to allow the loops to 'timeshare' : + +1. let the GUI main loop block the python process when you want + interactive windows +2. let the CLI main loop block the python process and intermittently + run the GUI loop +3. fully embed python in the GUI (but this is basically writing a full + application) + +.. _cp_block_the_prompt: + +Blocking the prompt +------------------- + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + pyplot.show + pyplot.pause + + backend_bases.FigureCanvasBase.start_event_loop + backend_bases.FigureCanvasBase.stop_event_loop + + +The simplest "integration" is to start the GUI event loop in +'blocking' mode and take over the CLI. While the GUI event loop is +running you can not enter new commands into the prompt (your terminal +may echo the characters typed into the terminal, but they will not be +sent to the Python interpreter because it is busy running the GUI +event loop), but the figure windows will be responsive. Once the +event loop is stopped (leaving any still open figure windows +non-responsive) you will be able to use the prompt again. Re-starting +the event loop will make any open figure responsive again (and will +process any queued up user interaction). + +To start the event loop until all open figures are closed, use +`.pyplot.show` as :: + + pyplot.show(block=True) + +To start the event loop for a fixed amount of time (in seconds) use +`.pyplot.pause`. + +If you are not using `.pyplot` you can start and stop the event loops +via `.FigureCanvasBase.start_event_loop` and +`.FigureCanvasBase.stop_event_loop`. However, in most contexts where +you would not be using `.pyplot` you are embedding Matplotlib in a +large GUI application and the GUI event loop should already be running +for the application. + +Away from the prompt, this technique can be very useful if you want to +write a script that pauses for user interaction, or displays a figure +between polling for additional data. See :ref:`interactive_scripts` +for more details. + + +Input hook integration +---------------------- + +While running the GUI event loop in a blocking mode or explicitly +handling UI events is useful, we can do better! We really want to be +able to have a usable prompt **and** interactive figure windows. + +We can do this using the 'input hook' feature of the interactive +prompt. This hook is called by the prompt as it waits for the user +to type (even for a fast typist the prompt is mostly waiting for the +human to think and move their fingers). Although the details vary +between prompts the logic is roughly + +1. start to wait for keyboard input +2. start the GUI event loop +3. as soon as the user hits a key, exit the GUI event loop and handle the key +4. repeat + +This gives us the illusion of simultaneously having interactive GUI +windows and an interactive prompt. Most of the time the GUI event +loop is running, but as soon as the user starts typing the prompt +takes over again. + +This time-share technique only allows the event loop to run while +python is otherwise idle and waiting for user input. If you want the +GUI to be responsive during long running code it is necessary to +periodically flush the GUI event queue as described in :ref:`spin_event_loop`. +In this case it is your code, not the REPL, which +is blocking the process so you need to handle the "time-share" manually. +Conversely, a very slow figure draw will block the prompt until it +finishes drawing. + +Full embedding +============== + +It is also possible to go the other direction and fully embed figures +(and a `Python interpreter +`__) in a rich +native application. Matplotlib provides classes for each toolkit +which can be directly embedded in GUI applications (this is how the +built-in windows are implemented!). See :ref:`user_interfaces` for +more details. + + +.. _interactive_scripts : + +Scripts and functions +===================== + + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + backend_bases.FigureCanvasBase.flush_events + backend_bases.FigureCanvasBase.draw_idle + + figure.Figure.ginput + pyplot.ginput + + pyplot.show + pyplot.pause + +There are several use-cases for using interactive figures in scripts: + +- capture user input to steer the script +- progress updates as a long running script progresses +- streaming updates from a data source + +Blocking functions +------------------ + +If you only need to collect points in an Axes you can use +`.Figure.ginput`. However if you have written some custom event +handling or are using `.widgets` you will need to manually run the GUI +event loop using the methods described :ref:`above `. + +You can also use the methods described in :ref:`cp_block_the_prompt` +to suspend run the GUI event loop. Once the loop exits your code will +resume. In general, any place you would use `time.sleep` you can use +`.pyplot.pause` instead with the added benefit of interactive figures. + +For example, if you want to poll for data you could use something like :: + + fig, ax = plt.subplots() + ln, = ax.plot([], []) + + while True: + x, y = get_new_data() + ln.set_data(x, y) + plt.pause(1) + +which would poll for new data and update the figure at 1Hz. + +.. _spin_event_loop: + +Explicitly spinning the event Loop +---------------------------------- + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + backend_bases.FigureCanvasBase.flush_events + backend_bases.FigureCanvasBase.draw_idle + + + +If you have open windows that have pending UI +events (mouse clicks, button presses, or draws) you can explicitly +process those events by calling `.FigureCanvasBase.flush_events`. +This will run the GUI event loop until all UI events currently waiting +have been processed. The exact behavior is backend-dependent but +typically events on all figure are processed and only events waiting +to be processed (not those added during processing) will be handled. + +For example :: + + import time + import matplotlib.pyplot as plt + import numpy as np + plt.ion() + + fig, ax = plt.subplots() + th = np.linspace(0, 2*np.pi, 512) + ax.set_ylim(-1.5, 1.5) + + ln, = ax.plot(th, np.sin(th)) + + def slow_loop(N, ln): + for j in range(N): + time.sleep(.1) # to simulate some work + ln.figure.canvas.flush_events() + + slow_loop(100, ln) + +While this will feel a bit laggy (as we are only processing user input +every 100ms whereas 20-30ms is what feels "responsive") it will +respond. + +If you make changes to the plot and want it re-rendered you will need +to call `~.FigureCanvasBase.draw_idle` to request that the canvas be +re-drawn. This method can be thought of *draw_soon* in analogy to +`asyncio.loop.call_soon`. + +We can add this to our example above as :: + + def slow_loop(N, ln): + for j in range(N): + time.sleep(.1) # to simulate some work + if j % 10: + ln.set_ydata(np.sin(((j // 10) % 5 * th))) + ln.figure.canvas.draw_idle() + + ln.figure.canvas.flush_events() + + slow_loop(100, ln) + + +The more frequently you call `.FigureCanvasBase.flush_events` the more +responsive your figure will feel but at the cost of spending more +resources on the visualization and less on your computation. + + +.. _stale_artists: + +Stale artists +============= + +Artists (as of Matplotlib 1.5) have a **stale** attribute which is +`True` if the internal state of the artist has changed since the last +time it was rendered. By default the stale state is propagated up to +the Artists parents in the draw tree, e.g., if the color of a `.Line2D` +instance is changed, the `~.axes.Axes` and `.Figure` that +contain it will also be marked as "stale". Thus, ``fig.stale`` will +report if any artist in the figure has been modified and is out of sync +with what is displayed on the screen. This is intended to be used to +determine if ``draw_idle`` should be called to schedule a re-rendering +of the figure. + +Each artist has a `.Artist.stale_callback` attribute which holds a callback +with the signature :: + + def callback(self: Artist, val: bool) -> None: + ... + +which by default is set to a function that forwards the stale state to +the artist's parent. If you wish to suppress a given artist from propagating +set this attribute to None. + +`.Figure` instances do not have a containing artist and their +default callback is `None`. If you call `.pyplot.ion` and are not in +``IPython`` we will install a callback to invoke +`~.backend_bases.FigureCanvasBase.draw_idle` whenever the +`.Figure` becomes stale. In ``IPython`` we use the +``'post_execute'`` hook to invoke +`~.backend_bases.FigureCanvasBase.draw_idle` on any stale figures +after having executed the user's input, but before returning the prompt +to the user. If you are not using `.pyplot` you can use the callback +`Figure.stale_callback` attribute to be notified when a figure has +become stale. + + +.. _draw_idle: + +Idle draw +========= + +.. autosummary:: + :template: autosummary.rst + :nosignatures: + + backend_bases.FigureCanvasBase.draw + backend_bases.FigureCanvasBase.draw_idle + backend_bases.FigureCanvasBase.flush_events + + +In almost all cases, we recommend using +`backend_bases.FigureCanvasBase.draw_idle` over +`backend_bases.FigureCanvasBase.draw`. ``draw`` forces a rendering of +the figure whereas ``draw_idle`` schedules a rendering the next time +the GUI window is going to re-paint the screen. This improves +performance by only rendering pixels that will be shown on the screen. If +you want to be sure that the screen is updated as soon as possible do :: + + fig.canvas.draw_idle() + fig.canvas.flush_events() + + + +Threading +========= + +Most GUI frameworks require that all updates to the screen, and hence +their main event loop, run on the main thread. This makes pushing +periodic updates of a plot to a background thread impossible. +Although it seems backwards, it is typically easier to push your +computations to a background thread and periodically update +the figure on the main thread. + +In general Matplotlib is not thread safe. If you are going to update +`.Artist` objects in one thread and draw from another you should make +sure that you are locking in the critical sections. + + + +Eventloop integration mechanism +=============================== + +CPython / readline +------------------ + +The Python C API provides a hook, :c:data:`PyOS_InputHook`, to register a +function to be run ("The function will be called when Python's +interpreter prompt is about to become idle and wait for user input +from the terminal."). This hook can be used to integrate a second +event loop (the GUI event loop) with the python input prompt loop. +The hook functions typically exhaust all pending events on the GUI +event queue, run the main loop for a short fixed amount of time, or +run the event loop until a key is pressed on stdin. + +Matplotlib does not currently do any management of :c:data:`PyOS_InputHook` due +to the wide range of ways that Matplotlib is used. This management is left to +downstream libraries -- either user code or the shell. Interactive figures, +even with Matplotlib in 'interactive mode', may not work in the vanilla python +repl if an appropriate :c:data:`PyOS_InputHook` is not registered. + +Input hooks, and helpers to install them, are usually included with +the python bindings for GUI toolkits and may be registered on import. +IPython also ships input hook functions for all of the GUI frameworks +Matplotlib supports which can be installed via ``%matplotlib``. This +is the recommended method of integrating Matplotlib and a prompt. + + +IPython / prompt_toolkit +------------------------ + +With IPython >= 5.0 IPython has changed from using CPython's readline +based prompt to a ``prompt_toolkit`` based prompt. ``prompt_toolkit`` +has the same conceptual input hook, which is fed into ``prompt_toolkit`` via the +:meth:`IPython.terminal.interactiveshell.TerminalInteractiveShell.inputhook` +method. The source for the ``prompt_toolkit`` input hooks lives at +``IPython.terminal.pt_inputhooks``. + + + +.. rubric:: Footnotes + +.. [#f1] A limitation of this design is that you can only wait for one + input, if there is a need to multiplex between multiple sources + then the loop would look something like :: + + fds = [...] + while True: # Loop + inp = select(fds).read() # Read + eval(inp) # Evaluate / Print + +.. [#f2] Or you can `write your own + `__ if you must. + +.. [#f3] These examples are aggressively dropping many of the + complexities that must be dealt with in the real world such as + keyboard interrupts, timeouts, bad input, resource + allocation and cleanup, etc. diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index a5ca1e23f608..ad7513ff9dd3 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -10,6 +10,7 @@ Explanations quick_start figure/index + axes/index backends.rst fonts.rst event_handling.rst From f32e96448191997ba09a69f5f24551e9b2cedb01 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 3 Mar 2023 16:46:00 -0800 Subject: [PATCH 04/23] DOC: axes --- .../axes}/arranging_axes.py | 1 + .../axes}/colorbar_placement.py | 2 + .../axes}/constrainedlayout_guide.py | 3 + galleries/users_explain/axes/index.rst | 175 ++++++++++++++++++ .../axes}/mosaic.py | 1 + .../axes}/tight_layout_guide.py | 2 + 6 files changed, 184 insertions(+) rename galleries/{tutorials/intermediate => users_explain/axes}/arranging_axes.py (99%) rename galleries/{examples/subplots_axes_and_figures => users_explain/axes}/colorbar_placement.py (97%) rename galleries/{tutorials/intermediate => users_explain/axes}/constrainedlayout_guide.py (99%) create mode 100644 galleries/users_explain/axes/index.rst rename galleries/{examples/subplots_axes_and_figures => users_explain/axes}/mosaic.py (99%) rename galleries/{tutorials/intermediate => users_explain/axes}/tight_layout_guide.py (99%) diff --git a/galleries/tutorials/intermediate/arranging_axes.py b/galleries/users_explain/axes/arranging_axes.py similarity index 99% rename from galleries/tutorials/intermediate/arranging_axes.py rename to galleries/users_explain/axes/arranging_axes.py index a0d91943ee18..f90dc3474e72 100644 --- a/galleries/tutorials/intermediate/arranging_axes.py +++ b/galleries/users_explain/axes/arranging_axes.py @@ -1,5 +1,6 @@ """ .. redirect-from:: /tutorials/intermediate/gridspec +.. redirect-from:: /tutorials/intermediate/arranging_axes .. _arranging_axes: diff --git a/galleries/examples/subplots_axes_and_figures/colorbar_placement.py b/galleries/users_explain/axes/colorbar_placement.py similarity index 97% rename from galleries/examples/subplots_axes_and_figures/colorbar_placement.py rename to galleries/users_explain/axes/colorbar_placement.py index f9eef05368c9..de767a4fa130 100644 --- a/galleries/examples/subplots_axes_and_figures/colorbar_placement.py +++ b/galleries/users_explain/axes/colorbar_placement.py @@ -1,6 +1,8 @@ """ .. _colorbar_placement: +.. redirect-from:: /gallery/subplots_axes_and_figures/colorbar_placement + ================= Placing Colorbars ================= diff --git a/galleries/tutorials/intermediate/constrainedlayout_guide.py b/galleries/users_explain/axes/constrainedlayout_guide.py similarity index 99% rename from galleries/tutorials/intermediate/constrainedlayout_guide.py rename to galleries/users_explain/axes/constrainedlayout_guide.py index cb4c639f198b..52080611f333 100644 --- a/galleries/tutorials/intermediate/constrainedlayout_guide.py +++ b/galleries/users_explain/axes/constrainedlayout_guide.py @@ -1,4 +1,7 @@ """ + +.. redirect-from:: /tutorials/intermediate/constrainedlayout_guide + ================================ Constrained Layout Guide ================================ diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst new file mode 100644 index 000000000000..6b5852d41227 --- /dev/null +++ b/galleries/users_explain/axes/index.rst @@ -0,0 +1,175 @@ +################## +Axes (or Subplots) +################## + + +Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods that can be used to add data to the Axes. An Axes typically has a pair of :ref:`Axis <../axis/>` Artists that define the data co-ordinate system, and include methods to add annotations like x- and y-labels, titles, and legends. + + +.. _anatomy_local: + +.. figure:: /_static/anatomy.png + :width: 80% + + Anatomy of a Figure + +In the picture above, the Axes object was created with ``ax = fig.subplots()``. +Everything else on the figure was created with methods on this ``ax`` object, +or can be accessed from it. If we want to change the label on the x-axis, we +call ``ax.set_xlabel('New Label')``, if we want to plot some data we call +``ax.plot(x, y)``. Indeed, in the figure above, the only Artist that is not +part of the Axes is the Figure itself, so the `.axes.Axes` class is really the +gateway to much of Matplotlib's functionality. + +Note that Axes are so fundamental to the operation of Matplotlib that a lot of +material here is duplicate of that in :ref:`quick_start`. + +Creating Axes +------------- + +.. plot:: + :include-source: + + import matplotlib.pyplot as plt + import numpy as np + + fig, axs = plt.subplots(ncols=2, nrows=2, figsize=(3.5, 2.5), + layout="constrained") + # for each Axes, add an artist, in this case a nice label in the middle... + for row in range(2): + for col in range(2): + axs[row, col].annotate(f'axs[{row}, {col}]', (0.5, 0.5), + transform=axs[row, col].transAxes, + ha='center', va='center', fontsize=18, + color='darkgrey') + fig.suptitle('plt.subplots()') + + +Axes are added using methods on `~.Figure` objects, or via the `~.pyplot` interface. These methods are discussed in more detail in :ref:`creating_figures` and :doc:`arranging_axes`. However, for instance `~.Figure.add_axes` will manually position an Axes on the page. In the example above `~.pyplot.subplots` put a grid of subplots on the figure, and ``axs`` is a (2, 2) array of Axes, each of which can have data added to them. + +There are a number of other methods for adding Axes to a Figure: + +* `.Figure.add_axes`: manually position an Axes. ``fig.add_axes([0, 0, 1, + 1])`` makes an Axes that fills the whole figure. +* `.pyplot.subplots` and `.Figure.subplots`: add a grid of Axes as in the example + above. The pyplot version returns both the Figure object and an array of + Axes. Note that ``fig, ax = plt.subplots()`` adds a single Axes to a Figure. +* `.pyplot.subplot_mosaic` and `.Figure.subplot_mosaic`: add a grid of named + Axes and return a dictionary of axes. For ``fig, axs = + plt.subplot_mosaic([['left', 'right'], ['bottom', 'bottom']])``, + ``axs['left']`` is an Axes in the top row on the left, and ``axs['bottom']`` + is an Axes that spans both columns on the bottom. + +See :doc:`arranging_axes` for more detail on how to arrange grids of Axes on a +Figure. + + +Axes plotting methods +--------------------- + +Most of the high-level plotting methods are accessed from the `.axes.Axes` class. See the API documentation for a full curated list, and :ref:`plot_types` for examples. A basic example is `.axes.Axes.plot`: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 3)) + np.random.seed(19680801) + t = np.arange(100) + x = np.cumsum(np.random.randn(100)) + lines = ax.plot(t, x) + +Note that ``plot`` returns a list of *lines* Artists which can subsequently be +manipulated, as discussed in :ref:`users_artists`. + +A very incomplete list of plotting methods is below. Again, see :ref:`plot_types` +for more examples, and `.axes.Axes` for the full list of methods. + +========================= ================================================== +:ref:`basic_plots` `~.axes.Axes.plot`, `~.axes.Axes.scatter`, + `~.axes.Axes.bar`, `~.axes.Axes.step`, +:ref:`arrays` `~.axes.Axes.pcolormesh`, `~.axes.Axes.contour`, + `~.axes.Axes.quiver`, `~.axes.Axes.streamplot`, + `~.axes.Axes.imshow` +:ref:`stats_plots` `~.axes.Axes.hist`, `~.axes.Axes.errorbar`, + `~.axes.Axes.hist2d`, `~.axes.Axes.pie`, + `~.axes.Axes.boxplot`, `~.axes.Axes.violinplot` +:ref:`unstructured_plots` `~.axes.Axes.tricontour`, `~.axes.Axes.tripcolor` +========================= ================================================== + +Axes labelling and annotation +----------------------------- + +Usually we want to label the Axes with an xlabel, ylabel, and title, and often we want to have a legend to differentiate plot elements. The `~.axes.Axes` class has a number of methods to create these annotations. + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(5, 3), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = np.cumsum(np.random.randn(200)) + y = np.cumsum(np.random.randn(200)) + linesx = ax.plot(t, x, label='Random walk x') + linesy = ax.plot(t, y, label='Random walk y') + + ax.set_xlabel('Time [s]') + ax.set_ylabel('Distance [km]') + ax.set_title('Random walk example') + ax.legend() + +These methods are relatively straight-forward, though there are a number of :ref:`text_props` that can be set on the text objects, like *fontsize*, *fontname*, *horizontalalignment*. Legends can be much more complicated; see :ref:`legend_guide` for more details. + +Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.Axes.annotate`. This can be quite sophisticated: see :ref:`text_props` and :ref:`annotations` for more information. + + + +Axes limits, scales, and ticking +-------------------------------- + +Each Axes has two (or more) `Axis` objects, that can be accessed via `~.axes.Axes.xaxis` and `~.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. + +Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.axes.Axes.set_ylim`), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = 2**np.cumsum(np.random.randn(200)) + linesx = ax.plot(t, x) + ax.set_yscale('log') + ax.set_xlim([20, 180]) + +The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels. Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`. + +Setting scales and controlling the Axis can be highly customized beyond these Axes-level helpers. An introduction to these methods can be found in :ref:`users_axis`, or the API reference for `.axis.Axis`. + + +Axes layout +----------- + +Sometimes it is important to set the aspect ratio of a plot in data space, which we can do with `~.axes.Axes.set_aspect`: + +.. plot:: + :include-source: + + fig, axs = plt.subplots(ncols=2, figsize=(7, 2.5), layout='constrained') + np.random.seed(19680801) + t = np.arange(200) + x = np.cumsum(np.random.randn(200)) + axs[0].plot(t, x) + axs[0].set_title('aspect="auto"') + + axs[1].plot(t, x) + axs[1].set_aspect(3) + axs[1].set_title('aspect=3') + +.. toctree:: + :maxdepth: 1 + + arranging_axes + colorbar_placement + In depth: subplot mosaic + In depth: Constrained layout guide + In depth: Tight layout guide (mildly discouraged) diff --git a/galleries/examples/subplots_axes_and_figures/mosaic.py b/galleries/users_explain/axes/mosaic.py similarity index 99% rename from galleries/examples/subplots_axes_and_figures/mosaic.py rename to galleries/users_explain/axes/mosaic.py index b0a5bd1bec9a..b21e583c67b4 100644 --- a/galleries/examples/subplots_axes_and_figures/mosaic.py +++ b/galleries/users_explain/axes/mosaic.py @@ -1,5 +1,6 @@ """ .. redirect-from:: /tutorials/provisional/mosaic +.. redirect-from:: /gallery/subplots_axes_and_figures/mosaic diff --git a/galleries/tutorials/intermediate/tight_layout_guide.py b/galleries/users_explain/axes/tight_layout_guide.py similarity index 99% rename from galleries/tutorials/intermediate/tight_layout_guide.py rename to galleries/users_explain/axes/tight_layout_guide.py index 60c3720b52a7..c136c3befaa4 100644 --- a/galleries/tutorials/intermediate/tight_layout_guide.py +++ b/galleries/users_explain/axes/tight_layout_guide.py @@ -1,4 +1,6 @@ """ +.. redirect_from:: /tutorial/intermediate/tight_layout_guide + ================== Tight Layout guide ================== From e8d6291b4588c313bfce2b0c5c2fe86857601b70 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 3 Mar 2023 17:16:54 -0800 Subject: [PATCH 05/23] DOC: colors --- galleries/{tutorials => users_explain}/colors/README.txt | 2 ++ galleries/{tutorials => users_explain}/colors/colorbar_only.py | 2 ++ .../colors/colormap-manipulation.py | 2 ++ galleries/{tutorials => users_explain}/colors/colormapnorms.py | 3 +++ galleries/{tutorials => users_explain}/colors/colormaps.py | 2 ++ galleries/{tutorials => users_explain}/colors/colors.py | 2 ++ galleries/users_explain/index.rst | 1 + 7 files changed, 14 insertions(+) rename galleries/{tutorials => users_explain}/colors/README.txt (88%) rename galleries/{tutorials => users_explain}/colors/colorbar_only.py (98%) rename galleries/{tutorials => users_explain}/colors/colormap-manipulation.py (99%) rename galleries/{tutorials => users_explain}/colors/colormapnorms.py (99%) rename galleries/{tutorials => users_explain}/colors/colormaps.py (99%) rename galleries/{tutorials => users_explain}/colors/colors.py (99%) diff --git a/galleries/tutorials/colors/README.txt b/galleries/users_explain/colors/README.txt similarity index 88% rename from galleries/tutorials/colors/README.txt rename to galleries/users_explain/colors/README.txt index e25b52994c52..79f49c523f56 100644 --- a/galleries/tutorials/colors/README.txt +++ b/galleries/users_explain/colors/README.txt @@ -1,5 +1,7 @@ .. _tutorials-colors: +.. redirect-from:: /tutorials/colors/index + Colors ------ diff --git a/galleries/tutorials/colors/colorbar_only.py b/galleries/users_explain/colors/colorbar_only.py similarity index 98% rename from galleries/tutorials/colors/colorbar_only.py rename to galleries/users_explain/colors/colorbar_only.py index 62e786da3e5e..f9f126533a16 100644 --- a/galleries/tutorials/colors/colorbar_only.py +++ b/galleries/users_explain/colors/colorbar_only.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/colors/colorbar_only + ============================= Customized Colorbars Tutorial ============================= diff --git a/galleries/tutorials/colors/colormap-manipulation.py b/galleries/users_explain/colors/colormap-manipulation.py similarity index 99% rename from galleries/tutorials/colors/colormap-manipulation.py rename to galleries/users_explain/colors/colormap-manipulation.py index cd8094fe0e34..4e517b91266c 100644 --- a/galleries/tutorials/colors/colormap-manipulation.py +++ b/galleries/users_explain/colors/colormap-manipulation.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/colors/colormap_manipulation + ******************************** Creating Colormaps in Matplotlib ******************************** diff --git a/galleries/tutorials/colors/colormapnorms.py b/galleries/users_explain/colors/colormapnorms.py similarity index 99% rename from galleries/tutorials/colors/colormapnorms.py rename to galleries/users_explain/colors/colormapnorms.py index 86fea0415fac..d505aff00d75 100644 --- a/galleries/tutorials/colors/colormapnorms.py +++ b/galleries/users_explain/colors/colormapnorms.py @@ -1,4 +1,7 @@ """ + +.. redirect-from:: /tutorials/colors/colormapnorms + Colormap Normalization ====================== diff --git a/galleries/tutorials/colors/colormaps.py b/galleries/users_explain/colors/colormaps.py similarity index 99% rename from galleries/tutorials/colors/colormaps.py rename to galleries/users_explain/colors/colormaps.py index 68f21ee1dd37..068213c247b3 100644 --- a/galleries/tutorials/colors/colormaps.py +++ b/galleries/users_explain/colors/colormaps.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/colors/colormaps + ******************************** Choosing Colormaps in Matplotlib ******************************** diff --git a/galleries/tutorials/colors/colors.py b/galleries/users_explain/colors/colors.py similarity index 99% rename from galleries/tutorials/colors/colors.py rename to galleries/users_explain/colors/colors.py index 62328743a09d..2f3d2070a30d 100644 --- a/galleries/tutorials/colors/colors.py +++ b/galleries/users_explain/colors/colors.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/colors/colors + ***************** Specifying colors ***************** diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index ad7513ff9dd3..904ee444c195 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -11,6 +11,7 @@ Explanations quick_start figure/index axes/index + colors/index backends.rst fonts.rst event_handling.rst From af95fcb9054a6297384e1b84e5d74faa5bd80f7e Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 3 Mar 2023 17:40:01 -0800 Subject: [PATCH 06/23] DOC: artists --- .../artists}/imshow_extent.py | 2 + galleries/users_explain/artists/index.rst | 196 ++++++++++++++++++ .../artists}/transforms_tutorial.py | 2 + galleries/users_explain/index.rst | 1 + 4 files changed, 201 insertions(+) rename galleries/{tutorials/intermediate => users_explain/artists}/imshow_extent.py (99%) create mode 100644 galleries/users_explain/artists/index.rst rename galleries/{tutorials/advanced => users_explain/artists}/transforms_tutorial.py (99%) diff --git a/galleries/tutorials/intermediate/imshow_extent.py b/galleries/users_explain/artists/imshow_extent.py similarity index 99% rename from galleries/tutorials/intermediate/imshow_extent.py rename to galleries/users_explain/artists/imshow_extent.py index 83ef00d5619b..1b391ca53e67 100644 --- a/galleries/tutorials/intermediate/imshow_extent.py +++ b/galleries/users_explain/artists/imshow_extent.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/intermediate/imshow_extent + *origin* and *extent* in `~.Axes.imshow` ======================================== diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst new file mode 100644 index 000000000000..9af802d25717 --- /dev/null +++ b/galleries/users_explain/artists/index.rst @@ -0,0 +1,196 @@ +.. _users_artists: + +Using Artists +------------- + +Almost all objects you interact with on a Matplotlib plot are called "Artist" +(and are subclasses of the `.Artist` class). :doc:`Figure <../figure/index>` +and :doc:`Axes <../axes/index>` are Artists, and generally contain :doc:`Axis +<../axis/index>` Artists and Artists that contain data or annotation +information. + + +Creating Artists +~~~~~~~~~~~~~~~~ + +Usually we do not instantiate Artists directly, but rather use a plotting +method on `~.axes.Axes`. Some examples of plotting methods and the Artist +object they create is given below: + +========================================= ================= +Axes helper method Artist +========================================= ================= +`~.axes.Axes.annotate` - text annotations `.Annotation` +`~.axes.Axes.bar` - bar charts `.Rectangle` +`~.axes.Axes.errorbar` - error bar plots `.Line2D` and + `.Rectangle` +`~.axes.Axes.fill` - shared area `.Polygon` +`~.axes.Axes.hist` - histograms `.Rectangle` +`~.axes.Axes.imshow` - image data `.AxesImage` +`~.axes.Axes.legend` - Axes legend `.Legend` +`~.axes.Axes.plot` - xy plots `.Line2D` +`~.axes.Axes.scatter` - scatter charts `.PolyCollection` +`~.axes.Axes.text` - text `.Text` +========================================= ================= + +As an example, we can save the Line2D Artist returned from `.axes.Axes.plot`: + +.. sourcecode:: ipython + + In [209]: import matplotlib.pyplot as plt + In [210]: import matplotlib.artist as martist + In [211]: import numpy as np + + In [212]: fig, ax = plt.subplots() + In [213]: x, y = np.random.rand(2, 100) + In [214]: lines = ax.plot(x, y, '-', label='example') + In [215]: print(lines) + [] + +Note that ``plot`` returns a _list_ of lines because you can pass in multiple x, +y pairs to plot. The line has been added to the Axes, and we can retrieve the +Artist via `~.Axes.get_lines()`: + +.. sourcecode:: ipython + + In [216]: print(ax.get_lines()) + + In [217]: print(ax.get_lines()[0]) + Line2D(example) + +Changing Artist properties +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Getting the ``lines`` object gives us access to all the properties of the +Line2D object. So if we want to change the *linewidth* after the fact, we can do so using `.Artist.set`. + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + x = np.arange(0, 13, 0.2) + y = np.sin(x) + lines = ax.plot(x, y, '-', label='example', linewidth=0.2, color='blue') + lines[0].set(color='green', linewidth=2) + +We can interrogate the full list of settable properties with +`matplotlib.artist.getp`: + +.. sourcecode:: ipython + + In [218]: martist.getp(lines[0]) + agg_filter = None + alpha = None + animated = False + antialiased or aa = True + bbox = Bbox(x0=0.004013842290585101, y0=0.013914221641967... + children = [] + clip_box = TransformedBbox( Bbox(x0=0.0, y0=0.0, x1=1.0, ... + clip_on = True + clip_path = None + color or c = blue + dash_capstyle = butt + dash_joinstyle = round + data = (array([0.91377845, 0.58456834, 0.36492019, 0.0379... + drawstyle or ds = default + figure = Figure(550x450) + fillstyle = full + gapcolor = None + gid = None + in_layout = True + label = example + linestyle or ls = - + linewidth or lw = 2.0 + marker = None + markeredgecolor or mec = blue + markeredgewidth or mew = 1.0 + markerfacecolor or mfc = blue + markerfacecoloralt or mfcalt = none + markersize or ms = 6.0 + markevery = None + mouseover = False + path = Path(array([[0.91377845, 0.51224793], [0.58... + path_effects = [] + picker = None + pickradius = 5 + rasterized = False + sketch_params = None + snap = None + solid_capstyle = projecting + solid_joinstyle = round + tightbbox = Bbox(x0=70.4609002763619, y0=54.321277798941786, x... + transform = CompositeGenericTransform( TransformWrapper( ... + transformed_clip_path_and_affine = (None, None) + url = None + visible = True + window_extent = Bbox(x0=70.4609002763619, y0=54.321277798941786, x... + xdata = [0.91377845 0.58456834 0.36492019 0.03796664 0.884... + xydata = [[0.91377845 0.51224793] [0.58456834 0.9820474 ] ... + ydata = [0.51224793 0.9820474 0.24469912 0.61647032 0.483... + zorder = 2 + +Note most Artists also have a distinct list of setters; e.g. +`.Line2D.set_color` or `.Line2D.set_linewidth`. + +Changing Artist data +~~~~~~~~~~~~~~~~~~~~ + +In addition to styling properties like *color* and *linewidth*, the Line2D +object has a *data* property. You can set the data after the line has been +created using `.Line2D.set_data`. This is often used for Animations, where the +same line is shown evolving over time (see :doc:`../animations`) + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + x = np.arange(0, 13, 0.2) + y = np.sin(x) + lines = ax.plot(x, y, '-', label='example') + lines[0].set_data([x, np.cos(x)]) + +Manually adding Artists +~~~~~~~~~~~~~~~~~~~~~~~ + +Not all Artists have helper methods, or you may want to use a low-level method +for some reason. For example the `.patches.Circle` Artist does not have a +helper, but we can still create and add to an Axes using the +`.axes.Axes.add_artist` method: + +.. plot:: + :include-source: + + import matplotlib.patches as mpatches + + fig, ax = plt.subplots(figsize=(4, 2.5)) + circle = mpatches.Circle((0.5, 0.5), 0.25, ec="none") + ax.add_artist(circle) + clipped_circle = mpatches.Circle((1, 0.5), 0.125, ec="none", facecolor='C1') + ax.add_artist(clipped_circle) + ax.set_aspect(1) + +The Circle takes the center and radius of the Circle as arguments to its +constructor; optional arguments are passed as keyword arguments. + +Note that when we add an Artist manually like this, it doesn't necessarily +adjust the axis limits like most of the helper methods do, so the Artists can +be clipped, as is the case above for the `clipped_circle` patch. + +See :doc:`artist_reference` for other patches. + +Removing Artists +~~~~~~~~~~~~~~~~ + +Sometimes we want to remove an Artist from a figure without re-specifying the +whole figure from scratch. Most Artists have a usable *remove* method that +will remove the Artist from its Axes list. For instance ``lines[0].remove()`` +would remove the *Line2D* artist created in the example above. + +More details +~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + imshow_extent + transforms_tutorial \ No newline at end of file diff --git a/galleries/tutorials/advanced/transforms_tutorial.py b/galleries/users_explain/artists/transforms_tutorial.py similarity index 99% rename from galleries/tutorials/advanced/transforms_tutorial.py rename to galleries/users_explain/artists/transforms_tutorial.py index d254464c2ba8..39e4c979b6ce 100644 --- a/galleries/tutorials/advanced/transforms_tutorial.py +++ b/galleries/users_explain/artists/transforms_tutorial.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/advanced/transforms_tutorial + ======================== Transformations Tutorial ======================== diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 904ee444c195..79e7512d65ab 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -11,6 +11,7 @@ Explanations quick_start figure/index axes/index + artists/index colors/index backends.rst fonts.rst From 087b9f621611bfb6ce982a3905a043767ebeeb0d Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 4 Mar 2023 14:02:42 -0800 Subject: [PATCH 07/23] DOC: fix most cross references --- .flake8 | 10 ++++----- .../prev_api_changes/api_changes_2.2.0.rst | 2 +- .../api_changes_3.4.0/behaviour.rst | 2 +- doc/devel/documenting_mpl.rst | 6 +++--- doc/index.rst | 2 +- doc/users/faq/howto_faq.rst | 4 ++-- doc/users/getting_started/index.rst | 4 ++-- .../prev_whats_new/dflt_style_changes.rst | 4 ++-- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/prev_whats_new/whats_new_1.0.rst | 2 +- doc/users/prev_whats_new/whats_new_1.1.rst | 2 +- doc/users/prev_whats_new/whats_new_2.2.rst | 2 +- doc/users/prev_whats_new/whats_new_3.3.0.rst | 2 +- doc/users/prev_whats_new/whats_new_3.4.0.rst | 4 ++-- galleries/examples/color/color_demo.py | 2 +- .../examples/color/colormap_reference.py | 4 ++-- galleries/examples/color/custom_cmap.py | 4 ++-- galleries/examples/color/named_colors.py | 2 +- .../contour_image.py | 4 ++-- .../images_contours_and_fields/image_demo.py | 4 ++-- .../lines_bars_and_markers/scatter_hist.py | 2 +- .../auto_subplots_adjust.py | 4 ++-- .../demo_constrained_layout.py | 4 ++-- .../demo_tight_layout.py | 4 ++-- .../gridspec_and_subplots.py | 2 +- .../angle_annotation.py | 4 ++-- .../placing_text_boxes.py | 2 +- .../tutorials/intermediate/legend_guide.py | 2 ++ galleries/tutorials/introductory/images.py | 4 ++-- galleries/tutorials/introductory/lifecycle.py | 4 ++-- galleries/tutorials/introductory/pyplot.py | 2 +- galleries/tutorials/text/annotations.py | 6 +++--- galleries/tutorials/text/text_props.py | 4 ++-- .../users_explain/artists/imshow_extent.py | 2 ++ .../artists/transforms_tutorial.py | 2 ++ .../users_explain/axes/arranging_axes.py | 9 ++++---- .../axes/constrainedlayout_guide.py | 6 ++++-- galleries/users_explain/axes/index.rst | 8 ++++--- galleries/users_explain/axes/mosaic.py | 4 ++-- .../users_explain/axes/tight_layout_guide.py | 10 +++++---- .../colors/colormap-manipulation.py | 8 ++++--- .../users_explain/colors/colormapnorms.py | 2 ++ galleries/users_explain/colors/colormaps.py | 4 +++- galleries/users_explain/colors/colors.py | 2 ++ galleries/users_explain/figure/index.rst | 8 +++---- galleries/users_explain/quick_start.py | 21 ++++++++++--------- lib/matplotlib/_constrained_layout.py | 4 ++-- lib/matplotlib/artist.py | 4 ++-- lib/matplotlib/axes/_axes.py | 4 ++-- lib/matplotlib/cm.py | 13 ++++++------ lib/matplotlib/colors.py | 10 ++++----- lib/matplotlib/figure.py | 14 ++++++------- lib/matplotlib/gridspec.py | 3 +-- lib/matplotlib/layout_engine.py | 4 ++-- lib/matplotlib/patches.py | 4 ++-- lib/matplotlib/pyplot.py | 4 ++-- lib/matplotlib/transforms.py | 2 +- pyproject.toml | 10 ++++----- 58 files changed, 146 insertions(+), 128 deletions(-) diff --git a/.flake8 b/.flake8 index 450b743e87b1..8f355cb7e5f7 100644 --- a/.flake8 +++ b/.flake8 @@ -57,13 +57,13 @@ per-file-ignores = doc/conf.py: E402 galleries/tutorials/advanced/path_tutorial.py: E402 galleries/tutorials/advanced/patheffects_guide.py: E402 - galleries/tutorials/advanced/transforms_tutorial.py: E402, E501 - galleries/tutorials/colors/colormaps.py: E501 - galleries/tutorials/colors/colors.py: E402 + galleries/users_explain/artists/transforms_tutorial.py: E402, E501 + galleries/users_explain/colormaps.py: E501 + galleries/users_explain/colors/colors.py: E402 galleries/tutorials/intermediate/artists.py: E402 - galleries/tutorials/intermediate/constrainedlayout_guide.py: E402 + galleries/users_explain/figure/constrainedlayout_guide.py: E402 galleries/tutorials/intermediate/legend_guide.py: E402 - galleries/tutorials/intermediate/tight_layout_guide.py: E402 + galleries/users_explain/figure/tight_layout_guide.py: E402 galleries/tutorials/introductory/animation_tutorial.py: E501 galleries/tutorials/introductory/images.py: E501 galleries/tutorials/introductory/pyplot.py: E402, E501 diff --git a/doc/api/prev_api_changes/api_changes_2.2.0.rst b/doc/api/prev_api_changes/api_changes_2.2.0.rst index f13fe2a246f0..83369b66f8ab 100644 --- a/doc/api/prev_api_changes/api_changes_2.2.0.rst +++ b/doc/api/prev_api_changes/api_changes_2.2.0.rst @@ -9,7 +9,7 @@ New dependency `kiwisolver `__ is now a required dependency to support the new constrained_layout, see -:doc:`/tutorials/intermediate/constrainedlayout_guide` for +:ref:`constrainedlayout_guide` for more details. diff --git a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst index f6d6459be8f1..df08097dba03 100644 --- a/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst +++ b/doc/api/prev_api_changes/api_changes_3.4.0/behaviour.rst @@ -24,7 +24,7 @@ library, so using it should be safe, but layouts may not be exactly the same as more development takes place. Details of using ``constrained_layout``, and its algorithm are available at -:doc:`/tutorials/intermediate/constrainedlayout_guide` +:ref:`constrainedlayout_guide` ``plt.subplot`` re-selection without keyword arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index 51c5f7e19eb0..a3090a6249a6 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -202,7 +202,7 @@ Documents can be linked with the ``:doc:`` directive: See the :doc:`/users/installing/index` - See the tutorial :doc:`/tutorials/introductory/quick_start` + See the tutorial :ref:`quick_start` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` @@ -210,7 +210,7 @@ will render as: See the :doc:`/users/installing/index` - See the tutorial :doc:`/tutorials/introductory/quick_start` + See the tutorial :ref:`quick_start` See the example :doc:`/gallery/lines_bars_and_markers/simple_plot` @@ -859,7 +859,7 @@ render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`. Tutorials are made with the exact same mechanism, except they are longer, and typically have more than one comment block (i.e. -:doc:`/tutorials/introductory/quick_start`). The first comment block +:ref:`quick_start`). The first comment block can be the same as the example above. Subsequent blocks of ReST text are delimited by the line ``# %%`` : diff --git a/doc/index.rst b/doc/index.rst index 1c608c0d62cb..ab811b59591c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -49,7 +49,7 @@ Learning resources Tutorials ^^^ - - :doc:`Quick-start guide ` + - :ref:`Quick-start guide ` - :doc:`Plot types ` - :ref:`Introductory tutorials ` - :doc:`External learning resources ` diff --git a/doc/users/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst index a7cd0ab0e643..00495d81dee2 100644 --- a/doc/users/faq/howto_faq.rst +++ b/doc/users/faq/howto_faq.rst @@ -183,8 +183,8 @@ multiple ways to fix this: `.pyplot.subplots_adjust`. - Use one of the automatic layout mechanisms: - - constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`) - - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`) + - constrained layout (:ref:`constrainedlayout_guide`) + - tight layout (:ref:`tight_layout_guide`) - Calculate good values from the size of the plot elements yourself (:doc:`/gallery/subplots_axes_and_figures/auto_subplots_adjust`) diff --git a/doc/users/getting_started/index.rst b/doc/users/getting_started/index.rst index ec1f769e5e78..68d62232ddc9 100644 --- a/doc/users/getting_started/index.rst +++ b/doc/users/getting_started/index.rst @@ -51,5 +51,5 @@ Where to go next - Check out :doc:`Plot types ` to get an overview of the types of plots you can create with Matplotlib. -- Learn Matplotlib from the ground up in the - :doc:`Quick-start guide `. +- Learn Matplotlib from the ground up in the :ref:`Quick-start guide + `. diff --git a/doc/users/prev_whats_new/dflt_style_changes.rst b/doc/users/prev_whats_new/dflt_style_changes.rst index 48ff86f56a73..9be573c050e3 100644 --- a/doc/users/prev_whats_new/dflt_style_changes.rst +++ b/doc/users/prev_whats_new/dflt_style_changes.rst @@ -98,7 +98,7 @@ are only specified via hex values. To access these colors outside of the property cycling the notation for colors ``'CN'``, where ``N`` takes values 0-9, was added to denote the first 10 colors in :rc:`axes.prop_cycle`. See -:doc:`/tutorials/colors/colors` for more details. +:ref:`colors_def` for more details. To restore the old color cycle use @@ -147,7 +147,7 @@ watch Nathaniel Smith and Stéfan van der Walt's talk from SciPy2015. See `here for many more details `__ about the other alternatives and the tools used to create the color map. For details on all of the colormaps available in matplotlib see -:doc:`/tutorials/colors/colormaps`. +:ref:`colormaps`. .. raw:: html diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index c2d761a25031..68f5442f7298 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -15,7 +15,7 @@ Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_gui and :ref:`plotting-guide-annotation`. Michael Sarahan has written :doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and -:doc:`/tutorials/advanced/transforms_tutorial`. +:doc:`transforms_tutorial`. .. _whats-new-mplot3d: diff --git a/doc/users/prev_whats_new/whats_new_1.0.rst b/doc/users/prev_whats_new/whats_new_1.0.rst index ab902977cb1e..c8da886c9097 100644 --- a/doc/users/prev_whats_new/whats_new_1.0.rst +++ b/doc/users/prev_whats_new/whats_new_1.0.rst @@ -23,7 +23,7 @@ Sophisticated subplot grid layout Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for doing complex subplot layouts, featuring row and column spans and -more. See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial +more. See :ref:`arranging_axes` for a tutorial overview. .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst index 901351466fac..a2c0ebf2045c 100644 --- a/doc/users/prev_whats_new/whats_new_1.1.rst +++ b/doc/users/prev_whats_new/whats_new_1.1.rst @@ -85,7 +85,7 @@ The usage of this functionality can be as simple as :: and it will adjust the spacing between subplots so that the axis labels do not overlap with neighboring subplots. A -:doc:`/tutorials/intermediate/tight_layout_guide` has been created to show how to use +:ref:`tight_layout_guide` has been created to show how to use this new tool. PyQT4, PySide, and IPython diff --git a/doc/users/prev_whats_new/whats_new_2.2.rst b/doc/users/prev_whats_new/whats_new_2.2.rst index 77b9056048f4..2071c131a5b2 100644 --- a/doc/users/prev_whats_new/whats_new_2.2.rst +++ b/doc/users/prev_whats_new/whats_new_2.2.rst @@ -32,7 +32,7 @@ Features include: - Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`. For more details and capabilities please see the new tutorial: - :doc:`/tutorials/intermediate/constrainedlayout_guide` + :ref:`constrainedlayout_guide` Note the new API to access this: diff --git a/doc/users/prev_whats_new/whats_new_3.3.0.rst b/doc/users/prev_whats_new/whats_new_3.3.0.rst index 58959627246a..45507b4c1dcf 100644 --- a/doc/users/prev_whats_new/whats_new_3.3.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.3.0.rst @@ -50,7 +50,7 @@ or as a string (with single-character Axes labels): ha='center', va='center', fontsize=36, color='darkgrey') -See :doc:`/gallery/subplots_axes_and_figures/mosaic` for more details and examples. +See :ref:`mosaic` for more details and examples. ``GridSpec.subplots()`` ----------------------- diff --git a/doc/users/prev_whats_new/whats_new_3.4.0.rst b/doc/users/prev_whats_new/whats_new_3.4.0.rst index 85a2f8a80975..6e9a3a82cf08 100644 --- a/doc/users/prev_whats_new/whats_new_3.4.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.4.0.rst @@ -582,7 +582,7 @@ If the center of symmetry is different from 0, it can be set with the *vcenter* argument. To manually set the range of `~.matplotlib.colors.CenteredNorm`, use the *halfrange* argument. -See :doc:`/tutorials/colors/colormapnorms` for an example and more details +See :ref:`colormapnorms` for an example and more details about data normalization. New ``FuncNorm`` for arbitrary normalizations @@ -617,7 +617,7 @@ forward and inverse. size=16, va='center', ha='center') plt.show() -See :doc:`/tutorials/colors/colormapnorms` for an example and more details +See :ref:`colormapnorms` for an example and more details about data normalization. GridSpec-based colorbars can now be positioned above or to the left of the main axes diff --git a/galleries/examples/color/color_demo.py b/galleries/examples/color/color_demo.py index b36585b2e188..8c4b7756cc3e 100644 --- a/galleries/examples/color/color_demo.py +++ b/galleries/examples/color/color_demo.py @@ -30,7 +30,7 @@ For more information on colors in matplotlib see -* the :doc:`/tutorials/colors/colors` tutorial; +* the :ref:`colors_def` tutorial; * the `matplotlib.colors` API; * the :doc:`/gallery/color/named_colors` example. """ diff --git a/galleries/examples/color/colormap_reference.py b/galleries/examples/color/colormap_reference.py index 09d4a1885116..ee01d7432b37 100644 --- a/galleries/examples/color/colormap_reference.py +++ b/galleries/examples/color/colormap_reference.py @@ -8,9 +8,9 @@ A reversed version of each of these colormaps is available by appending ``_r`` to the name, as shown in :ref:`reverse-cmap`. -See :doc:`/tutorials/colors/colormaps` for an in-depth discussion about +See :ref:`colormaps` for an in-depth discussion about colormaps, including colorblind-friendliness, and -:doc:`/tutorials/colors/colormap-manipulation` for a guide to creating +:ref:`colormap-manipulation` for a guide to creating colormaps. """ diff --git a/galleries/examples/color/custom_cmap.py b/galleries/examples/color/custom_cmap.py index da064401486e..ea3c06e13cac 100644 --- a/galleries/examples/color/custom_cmap.py +++ b/galleries/examples/color/custom_cmap.py @@ -4,9 +4,9 @@ ========================================= For more detail on creating and manipulating colormaps see -:doc:`/tutorials/colors/colormap-manipulation`. +:ref:`colormap-manipulation`. -Creating a :doc:`colormap ` from a list of colors +Creating a :ref:`colormap ` from a list of colors can be done with the `.LinearSegmentedColormap.from_list` method. You must pass a list of RGB tuples that define the mixture of colors from 0 to 1. diff --git a/galleries/examples/color/named_colors.py b/galleries/examples/color/named_colors.py index 9245bbb42727..c6cba68ab434 100644 --- a/galleries/examples/color/named_colors.py +++ b/galleries/examples/color/named_colors.py @@ -6,7 +6,7 @@ This plots a list of the named colors supported in matplotlib. For more information on colors in matplotlib see -* the :doc:`/tutorials/colors/colors` tutorial; +* the :ref:`colors_def` tutorial; * the `matplotlib.colors` API; * the :doc:`/gallery/color/color_demo`. diff --git a/galleries/examples/images_contours_and_fields/contour_image.py b/galleries/examples/images_contours_and_fields/contour_image.py index e03ec7a0402e..250256f4771f 100644 --- a/galleries/examples/images_contours_and_fields/contour_image.py +++ b/galleries/examples/images_contours_and_fields/contour_image.py @@ -9,8 +9,8 @@ The emphasis in this demo is on showing how to make contours register correctly on images, and on how to get both of them oriented as desired. -In particular, note the usage of the :doc:`"origin" and "extent" -` keyword arguments to imshow and +In particular, note the usage of the :ref:`"origin" and "extent" +` keyword arguments to imshow and contour. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/images_contours_and_fields/image_demo.py b/galleries/examples/images_contours_and_fields/image_demo.py index 295c48cf3bcd..884e68172698 100644 --- a/galleries/examples/images_contours_and_fields/image_demo.py +++ b/galleries/examples/images_contours_and_fields/image_demo.py @@ -134,8 +134,8 @@ # x[0, 0] in the upper left or lower right by using the origin parameter. # You can also control the default setting image.origin in your # :ref:`matplotlibrc file `. For more on -# this topic see the :doc:`complete guide on origin and extent -# `. +# this topic see the :ref:`complete guide on origin and extent +# `. x = np.arange(120).reshape((10, 12)) diff --git a/galleries/examples/lines_bars_and_markers/scatter_hist.py b/galleries/examples/lines_bars_and_markers/scatter_hist.py index 1ee745963a80..9e4598a15957 100644 --- a/galleries/examples/lines_bars_and_markers/scatter_hist.py +++ b/galleries/examples/lines_bars_and_markers/scatter_hist.py @@ -60,7 +60,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy): # -------------------------------------------- # # We define a gridspec with unequal width- and height-ratios to achieve desired -# layout. Also see the :doc:`/tutorials/intermediate/arranging_axes` tutorial. +# layout. Also see the :ref:`arranging_axes` tutorial. # Start with a square Figure. fig = plt.figure(figsize=(6, 6)) diff --git a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py index bf809061d59a..099ddc6e546a 100644 --- a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py +++ b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py @@ -12,8 +12,8 @@ almost always simpler and good enough to either set the subplot parameters manually using `.Figure.subplots_adjust`, or use one of the automatic layout mechanisms - (:doc:`/tutorials/intermediate/constrainedlayout_guide` or - :doc:`/tutorials/intermediate/tight_layout_guide`). + (:ref:`constrainedlayout_guide` or + :ref:`tight_layout_guide`). This example describes a user-defined way to read out Artist sizes and set the subplot parameters accordingly. Its main purpose is to illustrate diff --git a/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py b/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py index 2a375659dfc5..f16f419ece7a 100644 --- a/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py +++ b/galleries/examples/subplots_axes_and_figures/demo_constrained_layout.py @@ -7,8 +7,8 @@ a figure so that there are no overlaps between axes objects and labels on the axes. -See :doc:`/tutorials/intermediate/constrainedlayout_guide` for more details and -:doc:`/tutorials/intermediate/tight_layout_guide` for an alternative. +See :ref:`constrainedlayout_guide` for more details and +:ref:`tight_layout_guide` for an alternative. """ diff --git a/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py b/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py index 55b54c327a7b..0cc5f5301db4 100644 --- a/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py +++ b/galleries/examples/subplots_axes_and_figures/demo_tight_layout.py @@ -6,8 +6,8 @@ `~.Figure.tight_layout` attempts to resize subplots in a figure so that there are no overlaps between axes objects and labels on the axes. -See :doc:`/tutorials/intermediate/tight_layout_guide` for more details and -:doc:`/tutorials/intermediate/constrainedlayout_guide` for an alternative. +See :ref:`tight_layout_guide` for more details and +:ref:`constrainedlayout_guide` for an alternative. """ diff --git a/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py b/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py index 133fd37b5d71..bff3ea579e9e 100644 --- a/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py +++ b/galleries/examples/subplots_axes_and_figures/gridspec_and_subplots.py @@ -11,7 +11,7 @@ To start with this layout (rather than removing the overlapping axes) use `~.pyplot.subplot_mosaic`. -See also :doc:`/tutorials/intermediate/arranging_axes`. +See also :ref:`arranging_axes`. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/text_labels_and_annotations/angle_annotation.py b/galleries/examples/text_labels_and_annotations/angle_annotation.py index 97561c6c2f36..419d094bb6a9 100644 --- a/galleries/examples/text_labels_and_annotations/angle_annotation.py +++ b/galleries/examples/text_labels_and_annotations/angle_annotation.py @@ -21,8 +21,8 @@ * It provides a ready-to-use solution for the problem of easily drawing angles in graphs. * It shows how to subclass a Matplotlib artist to enhance its functionality, as - well as giving a hands-on example on how to use Matplotlib's :doc:`transform - system `. + well as giving a hands-on example on how to use Matplotlib's :ref:`transform + system `. If mainly interested in the former, you may copy the below class and jump to the :ref:`angle-annotation-usage` section. diff --git a/galleries/examples/text_labels_and_annotations/placing_text_boxes.py b/galleries/examples/text_labels_and_annotations/placing_text_boxes.py index c90921df9cba..f3b07a25e135 100644 --- a/galleries/examples/text_labels_and_annotations/placing_text_boxes.py +++ b/galleries/examples/text_labels_and_annotations/placing_text_boxes.py @@ -3,7 +3,7 @@ ================== When decorating axes with text boxes, two useful tricks are to place the text -in axes coordinates (see :doc:`/tutorials/advanced/transforms_tutorial`), +in axes coordinates (see :ref:`transforms_tutorial`), so the text doesn't move around with changes in x or y limits. You can also use the ``bbox`` property of text to surround the text with a `~matplotlib.patches.Patch` instance -- the ``bbox`` keyword argument takes a diff --git a/galleries/tutorials/intermediate/legend_guide.py b/galleries/tutorials/intermediate/legend_guide.py index 5c83ec57d0d3..cca977ccf018 100644 --- a/galleries/tutorials/intermediate/legend_guide.py +++ b/galleries/tutorials/intermediate/legend_guide.py @@ -1,4 +1,6 @@ """ +.. _legend_guide: + ============ Legend guide ============ diff --git a/galleries/tutorials/introductory/images.py b/galleries/tutorials/introductory/images.py index fc17b90f5aea..2e6b6376f723 100644 --- a/galleries/tutorials/introductory/images.py +++ b/galleries/tutorials/introductory/images.py @@ -42,8 +42,8 @@ experimenting with various plot settings. The alternative is the explicit, which is more suitable for large application development. For an explanation of the tradeoffs between the implicit and explicit interfaces see -:ref:`api_interfaces` and the :doc:`Quick start guide -` to start using the explicit interface. +:ref:`api_interfaces` and the :ref:`Quick start guide +` to start using the explicit interface. For now, let's get on with the implicit approach: """ diff --git a/galleries/tutorials/introductory/lifecycle.py b/galleries/tutorials/introductory/lifecycle.py index f72197d869bd..a881ff903c68 100644 --- a/galleries/tutorials/introductory/lifecycle.py +++ b/galleries/tutorials/introductory/lifecycle.py @@ -85,8 +85,8 @@ # .. note:: # # Figures can have multiple axes on them. For information on how to do this, -# see the :doc:`Tight Layout tutorial -# `. +# see the :ref:`Tight Layout tutorial +# `. fig, ax = plt.subplots() diff --git a/galleries/tutorials/introductory/pyplot.py b/galleries/tutorials/introductory/pyplot.py index 8077e3255bba..d8d68503e5f1 100644 --- a/galleries/tutorials/introductory/pyplot.py +++ b/galleries/tutorials/introductory/pyplot.py @@ -4,7 +4,7 @@ =============== An introduction to the pyplot interface. Please also see -:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib +:ref:`quick_start` for an overview of how Matplotlib works and :ref:`api_interfaces` for an explanation of the trade-offs between the supported user APIs. diff --git a/galleries/tutorials/text/annotations.py b/galleries/tutorials/text/annotations.py index b7a1807f6c33..7d176497947d 100644 --- a/galleries/tutorials/text/annotations.py +++ b/galleries/tutorials/text/annotations.py @@ -559,7 +559,7 @@ def custom_box_style(x0, y0, width, height, mutation_size): # Some others more advanced options are: # # 1. A `.Transform` instance. For more information on transforms, see the -# :doc:`../advanced/transforms_tutorial` For example, the +# :ref:`transforms_tutorial` For example, the # ``Axes.transAxes`` transform positions the annotation relative to the Axes # coordinates and using it is therefore identical to setting the # coordinate system to "axes fraction": @@ -689,7 +689,7 @@ def custom_box_style(x0, y0, width, height, mutation_size): # (with `~.Figure.add_artist`) rather than to either axes. This ensures that # the ConnectionPatch artist is drawn on top of both axes, and is also necessary # when using :doc:`constrained_layout -# ` for positioning the axes. +# <:ref:`constrainedlayout_guide`>` for positioning the axes. # # Zoom effect between Axes # ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -703,5 +703,5 @@ def custom_box_style(x0, y0, width, height, mutation_size): # # The code for this figure is at # :doc:`/gallery/subplots_axes_and_figures/axes_zoom_effect` and -# familiarity with :doc:`../advanced/transforms_tutorial` +# familiarity with :ref:`transforms_tutorial` # is recommended. diff --git a/galleries/tutorials/text/text_props.py b/galleries/tutorials/text/text_props.py index 6ac870cab263..9f215ae6d716 100644 --- a/galleries/tutorials/text/text_props.py +++ b/galleries/tutorials/text/text_props.py @@ -13,12 +13,12 @@ Property Value Type ========================== ====================================================================================================================== alpha `float` -backgroundcolor any matplotlib :doc:`color ` +backgroundcolor any matplotlib :ref:`color ` bbox `~matplotlib.patches.Rectangle` prop dict plus key ``'pad'`` which is a pad in points clip_box a matplotlib.transform.Bbox instance clip_on bool clip_path a `~matplotlib.path.Path` instance and a `~matplotlib.transforms.Transform` instance, a `~matplotlib.patches.Patch` -color any matplotlib :doc:`color ` +color any matplotlib :ref:`color ` family [ ``'serif'`` | ``'sans-serif'`` | ``'cursive'`` | ``'fantasy'`` | ``'monospace'`` ] fontproperties `~matplotlib.font_manager.FontProperties` horizontalalignment or ha [ ``'center'`` | ``'right'`` | ``'left'`` ] diff --git a/galleries/users_explain/artists/imshow_extent.py b/galleries/users_explain/artists/imshow_extent.py index 1b391ca53e67..849758689ca5 100644 --- a/galleries/users_explain/artists/imshow_extent.py +++ b/galleries/users_explain/artists/imshow_extent.py @@ -1,6 +1,8 @@ """ .. redirect-from:: /tutorials/intermediate/imshow_extent +.. _imshow_extent: + *origin* and *extent* in `~.Axes.imshow` ======================================== diff --git a/galleries/users_explain/artists/transforms_tutorial.py b/galleries/users_explain/artists/transforms_tutorial.py index 39e4c979b6ce..0c544c8f5e20 100644 --- a/galleries/users_explain/artists/transforms_tutorial.py +++ b/galleries/users_explain/artists/transforms_tutorial.py @@ -1,6 +1,8 @@ """ .. redirect-from:: /tutorials/advanced/transforms_tutorial +.. _transforms_tutorial: + ======================== Transformations Tutorial ======================== diff --git a/galleries/users_explain/axes/arranging_axes.py b/galleries/users_explain/axes/arranging_axes.py index f90dc3474e72..b37da984c6fc 100644 --- a/galleries/users_explain/axes/arranging_axes.py +++ b/galleries/users_explain/axes/arranging_axes.py @@ -40,7 +40,7 @@ flexibility that Axes can also span rows or columns. The Axes are returned in a labelled dictionary instead of an array. See also `.Figure.subplot_mosaic` and - :doc:`/gallery/subplots_axes_and_figures/mosaic`. + :ref:`mosaic`. Sometimes it is natural to have more than one distinct group of Axes grids, in which case Matplotlib has the concept of `.SubFigure`: @@ -417,10 +417,9 @@ def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)): # More reading # ============ # -# - More details about :doc:`subplot mosaic -# `. -# - More details about :doc:`constrained layout -# `, used to align +# - More details about :ref:`subplot mosaic `. +# - More details about :ref:`constrained layout +# `, used to align # spacing in most of these examples. # # .. admonition:: References diff --git a/galleries/users_explain/axes/constrainedlayout_guide.py b/galleries/users_explain/axes/constrainedlayout_guide.py index 52080611f333..0a2752674c6a 100644 --- a/galleries/users_explain/axes/constrainedlayout_guide.py +++ b/galleries/users_explain/axes/constrainedlayout_guide.py @@ -2,6 +2,8 @@ .. redirect-from:: /tutorials/intermediate/constrainedlayout_guide +.. _constrainedlayout_guide: + ================================ Constrained Layout Guide ================================ @@ -12,8 +14,8 @@ labels, legends, and colorbars do not overlap, while still preserving the logical layout requested by the user. -*Constrained layout* is similar to :doc:`Tight -layout`, but is substantially more +*Constrained layout* is similar to :ref:`Tight +layout`, but is substantially more flexible. It handles colorbars placed on multiple Axes (:ref:`colorbar_placement`) nested layouts (`~.Figure.subfigures`) and Axes that span rows or columns (`~.pyplot.subplot_mosaic`), striving to align spines from diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 6b5852d41227..3339cdf121f8 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -3,8 +3,11 @@ Axes (or Subplots) ################## -Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods that can be used to add data to the Axes. An Axes typically has a pair of :ref:`Axis <../axis/>` Artists that define the data co-ordinate system, and include methods to add annotations like x- and y-labels, titles, and legends. - +Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. +Once an Axes is placed on a figure there are many methods that can be used to +add data to the Axes. An Axes typically has a pair of :ref:`Axis <../axis/>` +Artists that define the data co-ordinate system, and include methods to add +annotations like x- and y-labels, titles, and legends. .. _anatomy_local: @@ -122,7 +125,6 @@ These methods are relatively straight-forward, though there are a number of :ref Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.Axes.annotate`. This can be quite sophisticated: see :ref:`text_props` and :ref:`annotations` for more information. - Axes limits, scales, and ticking -------------------------------- diff --git a/galleries/users_explain/axes/mosaic.py b/galleries/users_explain/axes/mosaic.py index b21e583c67b4..88d4562c7af6 100644 --- a/galleries/users_explain/axes/mosaic.py +++ b/galleries/users_explain/axes/mosaic.py @@ -2,7 +2,7 @@ .. redirect-from:: /tutorials/provisional/mosaic .. redirect-from:: /gallery/subplots_axes_and_figures/mosaic - +.. _mosaic: ======================================================== Complex and semantic figure composition (subplot_mosaic) @@ -12,7 +12,7 @@ and verbose. For dense, even grids we have `.Figure.subplots` but for more complex layouts, such as Axes that span multiple columns / rows of the layout or leave some areas of the Figure blank, you can use -`.gridspec.GridSpec` (see :doc:`/tutorials/intermediate/arranging_axes`) or +`.gridspec.GridSpec` (see :ref:`arranging_axes`) or manually place your axes. `.Figure.subplot_mosaic` aims to provide an interface to visually lay out your axes (as either ASCII art or nested lists) to streamline this process. diff --git a/galleries/users_explain/axes/tight_layout_guide.py b/galleries/users_explain/axes/tight_layout_guide.py index c136c3befaa4..42c227b2e360 100644 --- a/galleries/users_explain/axes/tight_layout_guide.py +++ b/galleries/users_explain/axes/tight_layout_guide.py @@ -1,5 +1,7 @@ """ -.. redirect_from:: /tutorial/intermediate/tight_layout_guide +.. redirect-from:: /tutorial/intermediate/tight_layout_guide + +.. _tight_layout_guide: ================== Tight Layout guide @@ -12,8 +14,8 @@ feature and may not work for some cases. It only checks the extents of ticklabels, axis labels, and titles. -An alternative to *tight_layout* is :doc:`constrained_layout -`. +An alternative to *tight_layout* is :ref:`constrained_layout +`. Simple Example @@ -119,7 +121,7 @@ def example_plot(ax, fontsize=12): # %% # It works with subplots created with # :func:`~matplotlib.pyplot.subplot2grid`. In general, subplots created -# from the gridspec (:doc:`/tutorials/intermediate/arranging_axes`) will work. +# from the gridspec (:ref:`arranging_axes`) will work. plt.close('all') fig = plt.figure() diff --git a/galleries/users_explain/colors/colormap-manipulation.py b/galleries/users_explain/colors/colormap-manipulation.py index 4e517b91266c..88e4c5befaf0 100644 --- a/galleries/users_explain/colors/colormap-manipulation.py +++ b/galleries/users_explain/colors/colormap-manipulation.py @@ -1,5 +1,7 @@ """ -.. redirect-from:: /tutorials/colors/colormap_manipulation +.. redirect-from:: /tutorials/colors/colormap-manipulation + +.. _colormap-manipulation: ******************************** Creating Colormaps in Matplotlib @@ -26,7 +28,7 @@ ============================================ First, getting a named colormap, most of which are listed in -:doc:`/tutorials/colors/colormaps`, may be done using `.matplotlib.colormaps`, +:ref:`colormaps`, may be done using `.matplotlib.colormaps`, which returns a colormap object. The length of the list of colors used internally to define the colormap can be adjusted via `.Colormap.resampled`. Below we use a modest value of 8 so there are not a lot of values to look at. @@ -117,7 +119,7 @@ def plot_examples(colormaps): # %% # In fact, that list may contain any valid -# :doc:`Matplotlib color specification `. +# :ref:`Matplotlib color specification `. # Particularly useful for creating custom colormaps are (N, 4)-shaped arrays. # Because with the variety of numpy operations that we can do on a such an # array, carpentry of new colormaps from existing colormaps become quite diff --git a/galleries/users_explain/colors/colormapnorms.py b/galleries/users_explain/colors/colormapnorms.py index d505aff00d75..f375b3af805b 100644 --- a/galleries/users_explain/colors/colormapnorms.py +++ b/galleries/users_explain/colors/colormapnorms.py @@ -2,6 +2,8 @@ .. redirect-from:: /tutorials/colors/colormapnorms +.. _colormapnorms: + Colormap Normalization ====================== diff --git a/galleries/users_explain/colors/colormaps.py b/galleries/users_explain/colors/colormaps.py index 068213c247b3..a38dd2af0fc9 100644 --- a/galleries/users_explain/colors/colormaps.py +++ b/galleries/users_explain/colors/colormaps.py @@ -1,6 +1,8 @@ """ .. redirect-from:: /tutorials/colors/colormaps +.. _colormaps: + ******************************** Choosing Colormaps in Matplotlib ******************************** @@ -11,7 +13,7 @@ `Third-party colormaps`_ section of the Matplotlib documentation. Here we briefly discuss how to choose between the many options. For help on creating your own colormaps, see -:doc:`/tutorials/colors/colormap-manipulation`. +:ref:`colormap-manipulation`. Overview ======== diff --git a/galleries/users_explain/colors/colors.py b/galleries/users_explain/colors/colors.py index 2f3d2070a30d..29cedaaa3ef3 100644 --- a/galleries/users_explain/colors/colors.py +++ b/galleries/users_explain/colors/colors.py @@ -1,6 +1,8 @@ """ .. redirect-from:: /tutorials/colors/colors +.. _colors_def: + ***************** Specifying colors ***************** diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index afd38a9723cb..46b8a54d7e93 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -1,5 +1,5 @@ -.. redirect_from:: /users/explain/figure +.. redirect-from:: /users/explain/figure .. _figure_explanation: +++++++++++++++++ @@ -186,9 +186,9 @@ figure in expected ways, with *frameon* making the figure transparent if set to Finally, the user can specify a layout engine for the figure with the *layout* parameter. Currently Matplotlib supplies -:doc:`"constrained" `, +:ref:`"constrained" `, :ref:`"compressed" ` and -:doc:`"tight" ` layout engines. These +:ref:`"tight" ` layout engines. These rescale axes inside the Figure to prevent overlap of ticklabels, and try and align axes, and can save significant manual adjustment of artists on a Figure for many common cases. @@ -209,7 +209,7 @@ usually with care being taken to use the appropriate transform. Usually these include ``Figure.transFigure`` which ranges from 0 to 1 in each direction, and represents the fraction of the current Figure size, or ``Figure.dpi_scale_trans`` which will be in physical units of inches from the bottom left corner of the Figure -(see :doc:`/tutorials/advanced/transforms_tutorial` for more details). +(see :ref:`transforms_tutorial` for more details). .. _saving_figures: diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index 1b597f09a8c4..75374eccf9ad 100644 --- a/galleries/users_explain/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -1,4 +1,9 @@ """ +.. redirect-from:: /tutorials/introductory/usage +.. redirect-from:: /tutorials/introductory/quick_start + +.. _quick_start: + ***************** Quick start guide ***************** @@ -6,9 +11,6 @@ This tutorial covers some basic usage patterns and best practices to help you get started with Matplotlib. -.. redirect-from:: /tutorials/introductory/usage -.. redirect-from:: /tutorials/introductory/quick_start - """ import matplotlib.pyplot as plt @@ -254,7 +256,7 @@ def my_plotter(ax, data1, data2, param_dict): # ------ # # Matplotlib has a very flexible array of colors that are accepted for most -# Artists; see the :doc:`colors tutorial ` for a +# Artists; see :ref:`allowable color definitions ` for a # list of specifications. Some Artists will take multiple colors. i.e. for # a `~.Axes.scatter` plot, the edge of the markers can be different colors # from the interior: @@ -409,7 +411,7 @@ def my_plotter(ax, data1, data2, param_dict): # The scale sets the mapping from data values to spacing along the Axis. This # happens in both directions, and gets combined into a *transform*, which # is the way that Matplotlib maps from data coordinates to Axes, Figure, or -# screen coordinates. See :doc:`/tutorials/advanced/transforms_tutorial`. +# screen coordinates. See :ref:`transforms_tutorial`. # # Tick locators and formatters # ---------------------------- @@ -529,8 +531,8 @@ def my_plotter(ax, data1, data2, param_dict): # These are all examples of Artists that derive from `~.ScalarMappable` # objects. They all can set a linear mapping between *vmin* and *vmax* into # the colormap specified by *cmap*. Matplotlib has many colormaps to choose -# from (:doc:`/tutorials/colors/colormaps`) you can make your -# own (:doc:`/tutorials/colors/colormap-manipulation`) or download as +# from (:ref:`colormaps`) you can make your +# own (:ref:`colormap-manipulation`) or download as # `third-party packages # `_. # @@ -540,7 +542,7 @@ def my_plotter(ax, data1, data2, param_dict): # Sometimes we want a non-linear mapping of the data to the colormap, as # in the ``LogNorm`` example above. We do this by supplying the # ScalarMappable with the *norm* argument instead of *vmin* and *vmax*. -# More normalizations are shown at :doc:`/tutorials/colors/colormapnorms`. +# More normalizations are shown at :ref:`colormapnorms`. # # Colorbars # --------- @@ -577,8 +579,7 @@ def my_plotter(ax, data1, data2, param_dict): # %% # Matplotlib has quite sophisticated tools for arranging Axes: See -# :doc:`/tutorials/intermediate/arranging_axes` and -# :doc:`/gallery/subplots_axes_and_figures/mosaic`. +# :ref:`arranging_axes` and :ref:`mosaic`. # # # More reading diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py index 9554a156f1ec..fc09a407a36a 100644 --- a/lib/matplotlib/_constrained_layout.py +++ b/lib/matplotlib/_constrained_layout.py @@ -10,7 +10,7 @@ ``figure.subplots()`` or ``figure.add_subplots()`` will participate in the layout. Axes manually placed via ``figure.add_axes()`` will not. -See Tutorial: :doc:`/tutorials/intermediate/constrainedlayout_guide` +See Tutorial: :ref:`constrainedlayout_guide` General idea: ------------- @@ -43,7 +43,7 @@ columns and rows. It's possible that the margins take up the whole figure, in which case the algorithm is not applied and a warning is raised. -See the tutorial doc:`/tutorials/intermediate/constrainedlayout_guide` +See the tutorial :ref:`constrainedlayout_guide` for more discussion of the algorithm with examples. """ diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index 7e2b64b6304a..f8eeb2e224ab 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -857,7 +857,7 @@ def get_in_layout(self): Return boolean flag, ``True`` if artist is included in layout calculations. - E.g. :doc:`/tutorials/intermediate/constrainedlayout_guide`, + E.g. :ref:`constrainedlayout_guide`, `.Figure.tight_layout()`, and ``fig.savefig(fname, bbox_inches='tight')``. """ @@ -1080,7 +1080,7 @@ def set_animated(self, b): def set_in_layout(self, in_layout): """ Set if artist is to be included in layout calculations, - E.g. :doc:`/tutorials/intermediate/constrainedlayout_guide`, + E.g. :ref:`constrainedlayout_guide`, `.Figure.tight_layout()`, and ``fig.savefig(fname, bbox_inches='tight')``. diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 7d8e415ec17c..5cec7d87247f 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -5551,7 +5551,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None, Note that the vertical axis points upward for 'lower' but downward for 'upper'. - See the :doc:`/tutorials/intermediate/imshow_extent` tutorial for + See the :ref:`imshow_extent` tutorial for examples and a more detailed description. extent : floats (left, right, bottom, top), optional @@ -5572,7 +5572,7 @@ def imshow(self, X, cmap=None, norm=None, *, aspect=None, - For ``origin == 'lower'`` the default is ``(-0.5, numcols-0.5, -0.5, numrows-0.5)``. - See the :doc:`/tutorials/intermediate/imshow_extent` tutorial for + See the :ref:`imshow_extent` tutorial for examples and a more detailed description. filternorm : bool, default: True diff --git a/lib/matplotlib/cm.py b/lib/matplotlib/cm.py index 55c78e83ab62..38158db9564a 100644 --- a/lib/matplotlib/cm.py +++ b/lib/matplotlib/cm.py @@ -5,14 +5,13 @@ :doc:`/gallery/color/colormap_reference` for a list of builtin colormaps. - :doc:`/tutorials/colors/colormap-manipulation` for examples of how to - make colormaps. + :ref:`colormap-manipulation` for examples of how to make + colormaps. - :doc:`/tutorials/colors/colormaps` an in-depth discussion of - choosing colormaps. + :ref:`colormaps` an in-depth discussion of choosing + colormaps. - :doc:`/tutorials/colors/colormapnorms` for more details about data - normalization. + :ref:`colormapnorms` for more details about data normalization. """ from collections.abc import Mapping @@ -681,7 +680,7 @@ def changed(self): If given, this can be one of the following: - An instance of `.Normalize` or one of its subclasses - (see :doc:`/tutorials/colors/colormapnorms`). + (see :ref:`colormapnorms`). - A scale name, i.e. one of "linear", "log", "symlog", "logit", etc. For a list of available scales, call `matplotlib.scale.get_scale_names()`. In that case, a suitable `.Normalize` subclass is dynamically generated diff --git a/lib/matplotlib/colors.py b/lib/matplotlib/colors.py index 57be04062de5..304eccca1bd7 100644 --- a/lib/matplotlib/colors.py +++ b/lib/matplotlib/colors.py @@ -16,12 +16,12 @@ .. seealso:: - :doc:`/tutorials/colors/colormap-manipulation` for examples of how to + :ref:`colormap-manipulation` for examples of how to make colormaps and - :doc:`/tutorials/colors/colormaps` for a list of built-in colormaps. + :ref:`colormaps` for a list of built-in colormaps. - :doc:`/tutorials/colors/colormapnorms` for more details about data + :ref:`colormapnorms` for more details about data normalization More colormaps are available at palettable_. @@ -33,7 +33,7 @@ RGBA array (`to_rgba_array`). Caching is used for efficiency. Colors that Matplotlib recognizes are listed at -:doc:`/tutorials/colors/colors`. +:ref:`colors_def`. .. _palettable: https://jiffyclub.github.io/palettable/ .. _xkcd color survey: https://xkcd.com/color/rgb/ @@ -502,7 +502,7 @@ def to_hex(c, keep_alpha=False): Parameters ---------- - c : :doc:`color ` or `numpy.ma.masked` + c : :ref:`color ` or `numpy.ma.masked` keep_alpha : bool, default: False If False, use the ``#rrggbb`` format, otherwise use ``#rrggbbaa``. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 3db7a102a31b..ca85346306d0 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1805,7 +1805,7 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, This is a helper function to build complex GridSpec layouts visually. - See :doc:`/gallery/subplots_axes_and_figures/mosaic` + See :ref:`mosaic` for an example and full API documentation Parameters @@ -2266,7 +2266,7 @@ def get_constrained_layout(self): """ Return whether constrained layout is being used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. """ return self._parent.get_constrained_layout() @@ -2277,7 +2277,7 @@ def get_constrained_layout_pads(self, relative=False): Returns a list of ``w_pad, h_pad`` in inches and ``wspace`` and ``hspace`` as fractions of the subplot. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- @@ -2427,7 +2427,7 @@ def __init__(self, to avoid overlapping axes decorations. Can handle complex plot layouts and colorbars, and is thus recommended. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :ref:`constrainedlayout_guide` for examples. - 'compressed': uses the same algorithm as 'constrained', but @@ -2776,7 +2776,7 @@ def get_constrained_layout(self): """ Return whether constrained layout is being used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. """ return isinstance(self.get_layout_engine(), ConstrainedLayoutEngine) @@ -2819,7 +2819,7 @@ def set_constrained_layout_pads(self, **kwargs): Tip: The parameters can be passed from a dictionary by using ``fig.set_constrained_layout(**pad_dict)``. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- @@ -2853,7 +2853,7 @@ def get_constrained_layout_pads(self, relative=False): ``wspace`` and ``hspace`` as fractions of the subplot. All values are None if ``constrained_layout`` is not used. - See :doc:`/tutorials/intermediate/constrainedlayout_guide`. + See :ref:`constrainedlayout_guide`. Parameters ---------- diff --git a/lib/matplotlib/gridspec.py b/lib/matplotlib/gridspec.py index 11dc05b0e9d2..c9d5fbd1c7ed 100644 --- a/lib/matplotlib/gridspec.py +++ b/lib/matplotlib/gridspec.py @@ -7,8 +7,7 @@ Often, users need not access this module directly, and can use higher-level methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and -`~.Figure.subfigures`. See the tutorial -:doc:`/tutorials/intermediate/arranging_axes` for a guide. +`~.Figure.subfigures`. See the tutorial :ref:`arranging_axes` for a guide. """ import copy diff --git a/lib/matplotlib/layout_engine.py b/lib/matplotlib/layout_engine.py index a3eab93da329..9d4b8e8a681e 100644 --- a/lib/matplotlib/layout_engine.py +++ b/lib/matplotlib/layout_engine.py @@ -127,7 +127,7 @@ def execute(self, fig): class TightLayoutEngine(LayoutEngine): """ Implements the ``tight_layout`` geometry management. See - :doc:`/tutorials/intermediate/tight_layout_guide` for details. + :ref:`tight_layout_guide` for details. """ _adjust_compatible = True _colorbar_gridspec = True @@ -191,7 +191,7 @@ def set(self, *, pad=None, w_pad=None, h_pad=None, rect=None): class ConstrainedLayoutEngine(LayoutEngine): """ Implements the ``constrained_layout`` geometry management. See - :doc:`/tutorials/intermediate/constrainedlayout_guide` for details. + :ref:`constrainedlayout_guide` for details. """ _adjust_compatible = False diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index 6d583b0c0d15..15971525dcf1 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -4431,8 +4431,8 @@ def __init__(self, xyA, xyB, coordsA, coordsB=None, *, .. note:: Using `ConnectionPatch` across two `~.axes.Axes` instances - is not directly compatible with :doc:`constrained layout - `. Add the artist + is not directly compatible with :ref:`constrained layout + `. Add the artist directly to the `.Figure` instead of adding it to a specific Axes, or exclude it from the layout using ``con.set_in_layout(False)``. diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 5a71207a2af7..a2668375c49d 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -750,7 +750,7 @@ def figure(num=None, # autoincrement if None, else integer from 1-N to avoid overlapping axes decorations. Can handle complex plot layouts and colorbars, and is thus recommended. - See :doc:`/tutorials/intermediate/constrainedlayout_guide` + See :ref:`constrainedlayout_guide` for examples. - 'compressed': uses the same algorithm as 'constrained', but @@ -1514,7 +1514,7 @@ def subplot_mosaic(mosaic, *, sharex=False, sharey=False, This is a helper function to build complex GridSpec layouts visually. - See :doc:`/gallery/subplots_axes_and_figures/mosaic` + See :ref:`mosaic` for an example and full API documentation Parameters diff --git a/lib/matplotlib/transforms.py b/lib/matplotlib/transforms.py index 6b666234fc17..3ae18cbf3f30 100644 --- a/lib/matplotlib/transforms.py +++ b/lib/matplotlib/transforms.py @@ -28,7 +28,7 @@ The backends are not expected to handle non-affine transformations themselves. -See the tutorial :doc:`/tutorials/advanced/transforms_tutorial` for examples +See the tutorial :ref:`transforms_tutorial` for examples of how to use transforms. """ diff --git a/pyproject.toml b/pyproject.toml index 2ddd3cbdda06..06da90b94a96 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -114,13 +114,13 @@ convention = "numpy" "galleries/tutorials/advanced/path_tutorial.py" = ["E402"] "galleries/tutorials/advanced/patheffects_guide.py" = ["E402"] -"galleries/tutorials/advanced/transforms_tutorial.py" = ["E402", "E501"] -"galleries/tutorials/colors/colormaps.py" = ["E501"] -"galleries/tutorials/colors/colors.py" = ["E402"] +"galleries/users_explain/artists/transforms_tutorial.py" = ["E402", "E501"] +"galleries/users_explain/colors/colormaps.py" = ["E501"] +"galleries/users_explain/colors/colors.py" = ["E402"] "galleries/tutorials/intermediate/artists.py" = ["E402"] -"galleries/tutorials/intermediate/constrainedlayout_guide.py" = ["E402"] +"galleries/users_explain/figure/constrainedlayout_guide.py" = ["E402"] "galleries/tutorials/intermediate/legend_guide.py" = ["E402"] -"galleries/tutorials/intermediate/tight_layout_guide.py" = ["E402"] +"galleries/users_explain/figure/tight_layout_guide.py" = ["E402"] "galleries/tutorials/introductory/animation_tutorial.py" = ["E501"] "galleries/tutorials/introductory/images.py" = ["E501"] "galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] From 1620a1214d96d1d474de48ba29e78d8525a7f715 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sat, 4 Mar 2023 16:23:10 -0800 Subject: [PATCH 08/23] DOC: move text --- .flake8 | 8 +++--- doc/devel/MEP/MEP29.rst | 2 +- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/prev_whats_new/whats_new_1.2.rst | 2 +- doc/users/prev_whats_new/whats_new_3.7.0.rst | 2 +- .../marker_reference.py | 2 +- galleries/examples/pyplots/pyplot_text.py | 2 +- .../artist_reference.py | 2 ++ .../annotate_transform.py | 2 +- .../annotation_basic.py | 2 +- .../annotation_demo.py | 2 +- .../annotation_polar.py | 2 +- .../font_family_rc.py | 2 +- .../text_labels_and_annotations/tex_demo.py | 2 +- galleries/examples/widgets/textbox.py | 2 +- galleries/tutorials/introductory/pyplot.py | 8 +++--- galleries/users_explain/artists/index.rst | 4 +-- galleries/users_explain/axes/index.rst | 2 +- galleries/users_explain/fonts.rst | 6 ++--- galleries/users_explain/index.rst | 7 ++--- galleries/users_explain/quick_start.py | 10 +++---- .../text/README.txt | 2 ++ .../text/annotations.py | 27 ++++++++++--------- .../text/mathtext.py | 13 ++++++--- .../{tutorials => users_explain}/text/pgf.py | 13 ++++++--- .../text/text_intro.py | 11 +++++--- .../text/text_props.py | 8 ++++-- .../text/usetex.py | 10 ++++--- lib/matplotlib/markers.py | 2 +- lib/matplotlib/mathtext.py | 2 +- lib/matplotlib/mpl-data/matplotlibrc | 2 +- pyproject.toml | 8 +++--- 32 files changed, 101 insertions(+), 70 deletions(-) rename galleries/{tutorials => users_explain}/text/README.txt (89%) rename galleries/{tutorials => users_explain}/text/annotations.py (96%) rename galleries/{tutorials => users_explain}/text/mathtext.py (97%) rename galleries/{tutorials => users_explain}/text/pgf.py (96%) rename galleries/{tutorials => users_explain}/text/text_intro.py (98%) rename galleries/{tutorials => users_explain}/text/text_props.py (98%) rename galleries/{tutorials => users_explain}/text/usetex.py (96%) diff --git a/.flake8 b/.flake8 index 8f355cb7e5f7..ba0615439edc 100644 --- a/.flake8 +++ b/.flake8 @@ -67,10 +67,10 @@ per-file-ignores = galleries/tutorials/introductory/animation_tutorial.py: E501 galleries/tutorials/introductory/images.py: E501 galleries/tutorials/introductory/pyplot.py: E402, E501 - galleries/tutorials/text/annotations.py: E402, E501 - galleries/tutorials/text/mathtext.py: E501 - galleries/tutorials/text/text_intro.py: E402 - galleries/tutorials/text/text_props.py: E501 + galleries/users_explain/text/annotations.py: E402, E501 + galleries/users_explain/text/mathtext.py: E501 + galleries/users_explain/text/text_intro.py: E402 + galleries/users_explain/text/text_props.py: E501 galleries/examples/animation/frame_grabbing_sgskip.py: E402 galleries/examples/images_contours_and_fields/tricontour_demo.py: E201 diff --git a/doc/devel/MEP/MEP29.rst b/doc/devel/MEP/MEP29.rst index d937889d55de..fce4e3c5072c 100644 --- a/doc/devel/MEP/MEP29.rst +++ b/doc/devel/MEP/MEP29.rst @@ -54,7 +54,7 @@ Improvements to use the html.parser from the standard library. * Computation of text fragment positions could benefit from the OffsetFrom - class. See for example item 5 in `Using Complex Coordinates with Annotations `_ + class. See for example item 5 in `Using Complex Coordinates with Annotations `_ Problems -------- diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index 68f5442f7298..04156de65e9c 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -15,7 +15,7 @@ Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_gui and :ref:`plotting-guide-annotation`. Michael Sarahan has written :doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and -:doc:`transforms_tutorial`. +:ref:`transforms_tutorial`. .. _whats-new-mplot3d: diff --git a/doc/users/prev_whats_new/whats_new_1.2.rst b/doc/users/prev_whats_new/whats_new_1.2.rst index 3bfa20e671be..46856ab4fcf5 100644 --- a/doc/users/prev_whats_new/whats_new_1.2.rst +++ b/doc/users/prev_whats_new/whats_new_1.2.rst @@ -39,7 +39,7 @@ PGF/TikZ backend Peter Würtz wrote a backend that allows matplotlib to export figures as drawing commands for LaTeX. These can be processed by PdfLaTeX, XeLaTeX or LuaLaTeX using the PGF/TikZ package. Usage examples and documentation are -found in :doc:`/tutorials/text/pgf`. +found in :ref:`pgf`. .. image:: /_static/pgf_preamble.* diff --git a/doc/users/prev_whats_new/whats_new_3.7.0.rst b/doc/users/prev_whats_new/whats_new_3.7.0.rst index 96ac42be38f2..37991f79c508 100644 --- a/doc/users/prev_whats_new/whats_new_3.7.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.7.0.rst @@ -448,4 +448,4 @@ New & Improved Narrative Documentation * Brand new :doc:`Animations ` tutorial. * New grouped and stacked `bar chart <../../gallery/index.html#lines_bars_and_markers>`_ examples. * New section for new contributors and reorganized git instructions in the :ref:`contributing guide`. -* Restructured :doc:`/tutorials/text/annotations` tutorial. +* Restructured :ref:`annotations` tutorial. diff --git a/galleries/examples/lines_bars_and_markers/marker_reference.py b/galleries/examples/lines_bars_and_markers/marker_reference.py index 557f988b7c0c..f99afb08e143 100644 --- a/galleries/examples/lines_bars_and_markers/marker_reference.py +++ b/galleries/examples/lines_bars_and_markers/marker_reference.py @@ -101,7 +101,7 @@ def split_list(a_list): # Markers created from TeX symbols # ================================ # -# Use :doc:`MathText `, to use custom marker symbols, +# Use :ref:`MathText `, to use custom marker symbols, # like e.g. ``"$\u266B$"``. For an overview over the STIX font symbols refer # to the `STIX font table `_. # Also see the :doc:`/gallery/text_labels_and_annotations/stix_fonts_demo`. diff --git a/galleries/examples/pyplots/pyplot_text.py b/galleries/examples/pyplots/pyplot_text.py index f327e6014807..9fb9f4f1608c 100644 --- a/galleries/examples/pyplots/pyplot_text.py +++ b/galleries/examples/pyplots/pyplot_text.py @@ -8,7 +8,7 @@ objects can be placed in the axes using `~.pyplot.text`. You can use TeX-like mathematical typesetting in all texts; see also -:doc:`/tutorials/text/mathtext`. +:ref:`mathtext`. .. redirect-from:: /gallery/pyplots/pyplot_mathtext """ diff --git a/galleries/examples/shapes_and_collections/artist_reference.py b/galleries/examples/shapes_and_collections/artist_reference.py index 853cc21d10f1..048018a9898e 100644 --- a/galleries/examples/shapes_and_collections/artist_reference.py +++ b/galleries/examples/shapes_and_collections/artist_reference.py @@ -1,4 +1,6 @@ """ +.. _artist_reference: + ================================ Reference for Matplotlib artists ================================ diff --git a/galleries/examples/text_labels_and_annotations/annotate_transform.py b/galleries/examples/text_labels_and_annotations/annotate_transform.py index d2bfbcef4df9..b2ce1de6a0c1 100644 --- a/galleries/examples/text_labels_and_annotations/annotate_transform.py +++ b/galleries/examples/text_labels_and_annotations/annotate_transform.py @@ -5,7 +5,7 @@ This example shows how to use different coordinate systems for annotations. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotation tutorial`. .. redirect-from:: /gallery/pyplots/annotate_transform """ diff --git a/galleries/examples/text_labels_and_annotations/annotation_basic.py b/galleries/examples/text_labels_and_annotations/annotation_basic.py index 2a5b115a96b1..45211558ec44 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_basic.py +++ b/galleries/examples/text_labels_and_annotations/annotation_basic.py @@ -7,7 +7,7 @@ coordinates. We modify the defaults of the arrow, to "shrink" it. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotation tutorial`. .. redirect-from:: /gallery/pyplots/annotation_basic """ diff --git a/galleries/examples/text_labels_and_annotations/annotation_demo.py b/galleries/examples/text_labels_and_annotations/annotation_demo.py index a17b60d50e0d..972a920fbd12 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_demo.py +++ b/galleries/examples/text_labels_and_annotations/annotation_demo.py @@ -7,7 +7,7 @@ This includes highlighting specific points of interest and using various visual tools to call attention to this point. For a more complete and in-depth description of the annotation and text tools in Matplotlib, see the -:doc:`tutorial on annotation `. +:ref:`tutorial on annotation `. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/text_labels_and_annotations/annotation_polar.py b/galleries/examples/text_labels_and_annotations/annotation_polar.py index 910aaad6757b..bbd46478bced 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_polar.py +++ b/galleries/examples/text_labels_and_annotations/annotation_polar.py @@ -6,7 +6,7 @@ This example shows how to create an annotation on a polar graph. For a complete overview of the annotation capabilities, also see the -:doc:`annotation tutorial`. +:ref:`annotations`. .. redirect-from:: /gallery/pyplots/annotation_polar """ diff --git a/galleries/examples/text_labels_and_annotations/font_family_rc.py b/galleries/examples/text_labels_and_annotations/font_family_rc.py index f7fc4376383e..e87ca7dd9b21 100644 --- a/galleries/examples/text_labels_and_annotations/font_family_rc.py +++ b/galleries/examples/text_labels_and_annotations/font_family_rc.py @@ -7,7 +7,7 @@ family names of fonts installed on user's system, or generic-families (e.g., 'serif', 'sans-serif', 'monospace', 'fantasy' or 'cursive'), or a combination of both. -(see :doc:`font tutorial `) +(see :ref:`text_props`) In the example below, we are overriding the default sans-serif generic family to include a specific (Tahoma) font. (Note that the best way to achieve this diff --git a/galleries/examples/text_labels_and_annotations/tex_demo.py b/galleries/examples/text_labels_and_annotations/tex_demo.py index 4df40191660b..5eba9a14c2b7 100644 --- a/galleries/examples/text_labels_and_annotations/tex_demo.py +++ b/galleries/examples/text_labels_and_annotations/tex_demo.py @@ -5,7 +5,7 @@ You can use TeX to render all of your Matplotlib text by setting :rc:`text.usetex` to True. This requires that you have TeX and the other -dependencies described in the :doc:`/tutorials/text/usetex` tutorial properly +dependencies described in the :ref:`usetex` tutorial properly installed on your system. Matplotlib caches processed TeX expressions, so that only the first occurrence of an expression triggers a TeX compilation. Later occurrences reuse the rendered image from the cache and are thus faster. diff --git a/galleries/examples/widgets/textbox.py b/galleries/examples/widgets/textbox.py index de94ba1d3c02..5a9dd7ff6feb 100644 --- a/galleries/examples/widgets/textbox.py +++ b/galleries/examples/widgets/textbox.py @@ -9,7 +9,7 @@ user presses enter in the textbox or leaves the textbox. Note: The `matplotlib.widgets.TextBox` widget is different from the following -static elements: :doc:`/tutorials/text/annotations` and +static elements: :ref:`annotations` and :doc:`/gallery/text_labels_and_annotations/placing_text_boxes`. """ diff --git a/galleries/tutorials/introductory/pyplot.py b/galleries/tutorials/introductory/pyplot.py index d8d68503e5f1..ae59437a8d8d 100644 --- a/galleries/tutorials/introductory/pyplot.py +++ b/galleries/tutorials/introductory/pyplot.py @@ -325,7 +325,7 @@ def f(t): # # `~.pyplot.text` can be used to add text in an arbitrary location, and # `~.pyplot.xlabel`, `~.pyplot.ylabel` and `~.pyplot.title` are used to add -# text in the indicated locations (see :doc:`/tutorials/text/text_intro` for a +# text in the indicated locations (see :ref:`text_intro` for a # more detailed example) mu, sigma = 100, 15 @@ -350,7 +350,7 @@ def f(t): # # t = plt.xlabel('my data', fontsize=14, color='red') # -# These properties are covered in more detail in :doc:`/tutorials/text/text_props`. +# These properties are covered in more detail in :ref:`text_props`. # # # Using mathematical expressions in text @@ -366,11 +366,11 @@ def f(t): # that the string is a *raw* string and not to treat backslashes as # python escapes. matplotlib has a built-in TeX expression parser and # layout engine, and ships its own math fonts -- for details see -# :doc:`/tutorials/text/mathtext`. Thus, you can use mathematical text across +# :ref:`mathtext`. Thus, you can use mathematical text across # platforms without requiring a TeX installation. For those who have LaTeX # and dvipng installed, you can also use LaTeX to format your text and # incorporate the output directly into your display figures or saved -# postscript -- see :doc:`/tutorials/text/usetex`. +# postscript -- see :ref:`usetex`. # # # Annotating text diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index 9af802d25717..7f8dc7177577 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -174,9 +174,9 @@ constructor; optional arguments are passed as keyword arguments. Note that when we add an Artist manually like this, it doesn't necessarily adjust the axis limits like most of the helper methods do, so the Artists can -be clipped, as is the case above for the `clipped_circle` patch. +be clipped, as is the case above for the ``clipped_circle`` patch. -See :doc:`artist_reference` for other patches. +See :ref:`artist_reference` for other patches. Removing Artists ~~~~~~~~~~~~~~~~ diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 3339cdf121f8..4c616f06ec46 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -128,7 +128,7 @@ Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.A Axes limits, scales, and ticking -------------------------------- -Each Axes has two (or more) `Axis` objects, that can be accessed via `~.axes.Axes.xaxis` and `~.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. +Each Axes has two (or more) `~.axis.Axis` objects, that can be accessed via :attr:`~matplotlib.axes.Axes.xaxis` and :attr:`~matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.axes.Axes.set_ylim`), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data: diff --git a/galleries/users_explain/fonts.rst b/galleries/users_explain/fonts.rst index 1f12c5760d25..70c614a3c078 100644 --- a/galleries/users_explain/fonts.rst +++ b/galleries/users_explain/fonts.rst @@ -7,13 +7,13 @@ Matplotlib needs fonts to work with its text engine, some of which are shipped alongside the installation. The default font is `DejaVu Sans `_ which covers most European writing systems. However, users can configure the default fonts, and provide their own custom -fonts. See :doc:`Customizing text properties ` for +fonts. See :ref:`Customizing text properties ` for details and :ref:`font-nonlatin` in particular for glyphs not supported by DejaVu Sans. Matplotlib also provides an option to offload text rendering to a TeX engine -(``usetex=True``), see :doc:`Text rendering with LaTeX -`. +(``usetex=True``), see :ref:`Text rendering with LaTeX +`. Fonts in PDF and PostScript --------------------------- diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 79e7512d65ab..f4d6969e88c9 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -2,17 +2,18 @@ .. redirect-from:: /users/explain -Explanations ------------- +Using Matplotlib +---------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 quick_start figure/index axes/index artists/index colors/index + text/index backends.rst fonts.rst event_handling.rst diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index 75374eccf9ad..7ed93c2ea1c5 100644 --- a/galleries/users_explain/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -297,7 +297,7 @@ def my_plotter(ax, data1, data2, param_dict): # -------------------- # # `~.Axes.set_xlabel`, `~.Axes.set_ylabel`, and `~.Axes.set_title` are used to -# add text in the indicated locations (see :doc:`/tutorials/text/text_intro` +# add text in the indicated locations (see :ref:`text_intro` # for more discussion). Text can also be directly added to plots using # `~.Axes.text`: @@ -322,7 +322,7 @@ def my_plotter(ax, data1, data2, param_dict): # t = ax.set_xlabel('my data', fontsize=14, color='red') # # These properties are covered in more detail in -# :doc:`/tutorials/text/text_props`. +# :ref:`text_props`. # # Using mathematical expressions in text # -------------------------------------- @@ -337,9 +337,9 @@ def my_plotter(ax, data1, data2, param_dict): # *raw* string and not to treat backslashes as python escapes. # Matplotlib has a built-in TeX expression parser and # layout engine, and ships its own math fonts – for details see -# :doc:`/tutorials/text/mathtext`. You can also use LaTeX directly to format +# :ref:`mathtext`. You can also use LaTeX directly to format # your text and incorporate the output directly into your display figures or -# saved postscript – see :doc:`/tutorials/text/usetex`. +# saved postscript – see :ref:`usetex`. # # Annotations # ----------- @@ -552,7 +552,7 @@ def my_plotter(ax, data1, data2, param_dict): # a ScalarMappable (where they get their information about the norm and # colormap) and usually steal space from a parent Axes. Placement of # colorbars can be complex: see -# :doc:`/gallery/subplots_axes_and_figures/colorbar_placement` for +# :ref:`colorbar_placement` for # details. You can also change the appearance of colorbars with the # *extend* keyword to add arrows to the ends, and *shrink* and *aspect* to # control the size. Finally, the colorbar will have default locators diff --git a/galleries/tutorials/text/README.txt b/galleries/users_explain/text/README.txt similarity index 89% rename from galleries/tutorials/text/README.txt rename to galleries/users_explain/text/README.txt index 4eaaa4de9c23..8fe69bc0dba7 100644 --- a/galleries/tutorials/text/README.txt +++ b/galleries/users_explain/text/README.txt @@ -1,3 +1,5 @@ +.. redirect-from:: /tutorials/text + .. _tutorials-text: Text diff --git a/galleries/tutorials/text/annotations.py b/galleries/users_explain/text/annotations.py similarity index 96% rename from galleries/tutorials/text/annotations.py rename to galleries/users_explain/text/annotations.py index 7d176497947d..5864d2c3a997 100644 --- a/galleries/tutorials/text/annotations.py +++ b/galleries/users_explain/text/annotations.py @@ -6,6 +6,9 @@ .. redirect-from:: /gallery/userdemo/anchored_box04 .. redirect-from:: /gallery/userdemo/annotate_simple_coord01 .. redirect-from:: /gallery/userdemo/annotate_simple_coord03 +.. redirect-from:: /tutorials/text/annotations + +.. _annotations: Annotations =========== @@ -236,8 +239,8 @@ # Square ``square`` pad=0.3 # ========== ============== ========================== # -# .. figure:: ../../gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png -# :target: ../../gallery/shapes_and_collections/fancybox_demo.html +# .. figure:: /gallery/shapes_and_collections/images/sphx_glr_fancybox_demo_001.png +# :target: /gallery/shapes_and_collections/fancybox_demo.html # :align: center # # The patch object (box) associated with the text can be accessed using:: @@ -326,8 +329,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # 4. The path is transmuted to an arrow patch, as specified by the *arrowstyle* # parameter. # -# .. figure:: ../../gallery/userdemo/images/sphx_glr_annotate_explain_001.png -# :target: ../../gallery/userdemo/annotate_explain.html +# .. figure:: /gallery/userdemo/images/sphx_glr_annotate_explain_001.png +# :target: /gallery/userdemo/annotate_explain.html # :align: center # # The creation of the connecting path between two points is controlled by @@ -352,8 +355,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # example below. (Warning: The behavior of the ``bar`` style is currently not # well-defined and may be changed in the future). # -# .. figure:: ../../gallery/userdemo/images/sphx_glr_connectionstyle_demo_001.png -# :target: ../../gallery/userdemo/connectionstyle_demo.html +# .. figure:: /gallery/userdemo/images/sphx_glr_connectionstyle_demo_001.png +# :target: /gallery/userdemo/connectionstyle_demo.html # :align: center # # The connecting path (after clipping and shrinking) is then mutated to @@ -376,8 +379,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # ``wedge`` tail_width=0.3,shrink_factor=0.5 # ========== ============================================= # -# .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_fancyarrow_demo_001.png -# :target: ../../gallery/text_labels_and_annotations/fancyarrow_demo.html +# .. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_fancyarrow_demo_001.png +# :target: /gallery/text_labels_and_annotations/fancyarrow_demo.html # :align: center # # Some arrowstyles only work with connection styles that generate a @@ -688,8 +691,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # Here, we added the `.ConnectionPatch` to the *figure* # (with `~.Figure.add_artist`) rather than to either axes. This ensures that # the ConnectionPatch artist is drawn on top of both axes, and is also necessary -# when using :doc:`constrained_layout -# <:ref:`constrainedlayout_guide`>` for positioning the axes. +# when using :ref:`constrained_layout ` +# for positioning the axes. # # Zoom effect between Axes # ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -697,8 +700,8 @@ def custom_box_style(x0, y0, width, height, mutation_size): # `mpl_toolkits.axes_grid1.inset_locator` defines some patch classes useful for # interconnecting two axes. # -# .. figure:: ../../gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png -# :target: ../../gallery/subplots_axes_and_figures/axes_zoom_effect.html +# .. figure:: /gallery/subplots_axes_and_figures/images/sphx_glr_axes_zoom_effect_001.png +# :target: /gallery/subplots_axes_and_figures/axes_zoom_effect.html # :align: center # # The code for this figure is at diff --git a/galleries/tutorials/text/mathtext.py b/galleries/users_explain/text/mathtext.py similarity index 97% rename from galleries/tutorials/text/mathtext.py rename to galleries/users_explain/text/mathtext.py index 2be0d67ca3b0..b0812c67b221 100644 --- a/galleries/tutorials/text/mathtext.py +++ b/galleries/users_explain/text/mathtext.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/text/mathtext + +.. _mathtext: + Writing mathematical expressions ================================ @@ -10,7 +15,7 @@ is a fairly direct adaptation of the layout algorithms in Donald Knuth's TeX, so the quality is quite good (Matplotlib also provides a ``usetex`` option for those who do want to call out to TeX to generate their text; see -:doc:`/tutorials/text/usetex`). +:ref:`usetex`). Any text element can use math text. You should use raw strings (precede the quotes with an ``'r'``), and surround the math text with dollar signs ($), as @@ -50,7 +55,7 @@ have special meaning outside of math mode in TeX. Therefore, these characters will behave differently depending on :rc:`text.usetex`. See the - :doc:`usetex tutorial ` for more information. + :ref:`usetex tutorial ` for more information. Subscripts and superscripts --------------------------- @@ -354,7 +359,7 @@ ------- Here is an example illustrating many of these features in context. -.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_mathtext_demo_001.png - :target: ../../gallery/text_labels_and_annotations/mathtext_demo.html +.. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_mathtext_demo_001.png + :target: /gallery/text_labels_and_annotations/mathtext_demo.html :align: center """ diff --git a/galleries/tutorials/text/pgf.py b/galleries/users_explain/text/pgf.py similarity index 96% rename from galleries/tutorials/text/pgf.py rename to galleries/users_explain/text/pgf.py index 5cbf4cfa8b98..5dfd7e53f4a0 100644 --- a/galleries/tutorials/text/pgf.py +++ b/galleries/users_explain/text/pgf.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/text/pgf + +.. _pgf: + ************************************************************ Text rendering with XeLaTeX/LuaLaTeX via the ``pgf`` backend ************************************************************ @@ -100,7 +105,7 @@ When saving to ``.pgf``, the font configuration Matplotlib used for the layout of the figure is included in the header of the text file. -.. literalinclude:: ../../gallery/userdemo/pgf_fonts.py +.. literalinclude:: /gallery/userdemo/pgf_fonts.py :end-before: fig.savefig @@ -117,12 +122,12 @@ .. only:: html - .. literalinclude:: ../../gallery/userdemo/pgf_preamble_sgskip.py + .. literalinclude:: /gallery/userdemo/pgf_preamble_sgskip.py :end-before: fig.savefig .. only:: latex - .. literalinclude:: ../../gallery/userdemo/pgf_preamble_sgskip.py + .. literalinclude:: /gallery/userdemo/pgf_preamble_sgskip.py :end-before: import matplotlib.pyplot as plt @@ -136,7 +141,7 @@ Please note that when selecting pdflatex, the fonts and Unicode handling must be configured in the preamble. -.. literalinclude:: ../../gallery/userdemo/pgf_texsystem.py +.. literalinclude:: /gallery/userdemo/pgf_texsystem.py :end-before: fig.savefig diff --git a/galleries/tutorials/text/text_intro.py b/galleries/users_explain/text/text_intro.py similarity index 98% rename from galleries/tutorials/text/text_intro.py rename to galleries/users_explain/text/text_intro.py index 10aae0f40887..628531babdf4 100644 --- a/galleries/tutorials/text/text_intro.py +++ b/galleries/users_explain/text/text_intro.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/text/text_intro + +.. _text_intro: + ======================== Text in Matplotlib Plots ======================== @@ -24,8 +29,8 @@ the :doc:`rc file `. And significantly, for those interested in mathematical or scientific figures, Matplotlib implements a large number of TeX -math symbols and commands, supporting :doc:`mathematical expressions -` anywhere in your figure. +math symbols and commands, supporting :ref:`mathematical expressions +` anywhere in your figure. Basic text commands @@ -420,5 +425,5 @@ def formatoddticks(x, pos): # ======================= # # - Legends: :doc:`/tutorials/intermediate/legend_guide` -# - Annotations: :doc:`/tutorials/text/annotations` +# - Annotations: :ref:`annotations` # diff --git a/galleries/tutorials/text/text_props.py b/galleries/users_explain/text/text_props.py similarity index 98% rename from galleries/tutorials/text/text_props.py rename to galleries/users_explain/text/text_props.py index 9f215ae6d716..955197e37f02 100644 --- a/galleries/tutorials/text/text_props.py +++ b/galleries/users_explain/text/text_props.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/text/text_props + +.. _text_props: + ============================ Text properties and layout ============================ @@ -248,8 +253,7 @@ # font.family: Source Han Sans TW, Arial, sans-serif # # To control the font used on per-artist basis use the *name*, *fontname* or -# *fontproperties* keyword arguments documented :doc:`above -# `. +# *fontproperties* keyword arguments documented in :ref:`text_props`. # # # On linux, `fc-list `__ can be a diff --git a/galleries/tutorials/text/usetex.py b/galleries/users_explain/text/usetex.py similarity index 96% rename from galleries/tutorials/text/usetex.py rename to galleries/users_explain/text/usetex.py index 2b55864b18f6..97578c8b9380 100644 --- a/galleries/tutorials/text/usetex.py +++ b/galleries/users_explain/text/usetex.py @@ -1,4 +1,8 @@ r""" +.. redirect-from:: /tutorials/text/usetex + +.. _usetex: + ************************* Text rendering with LaTeX ************************* @@ -6,7 +10,7 @@ Matplotlib can use LaTeX to render text. This is activated by setting ``text.usetex : True`` in your rcParams, or by setting the ``usetex`` property to True on individual `.Text` objects. Text handling through LaTeX is slower -than Matplotlib's very capable :doc:`mathtext `, but +than Matplotlib's very capable :ref:`mathtext `, but is more flexible, since different LaTeX packages (font packages, math packages, etc.) can be used. The results can be striking, especially when you take care to use the same fonts in your figures as in the main document. @@ -71,8 +75,8 @@ Here is the standard example, :doc:`/gallery/text_labels_and_annotations/tex_demo`: -.. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png - :target: ../../gallery/text_labels_and_annotations/tex_demo.html +.. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png + :target: /gallery/text_labels_and_annotations/tex_demo.html :align: center Note that display math mode (``$$ e=mc^2 $$``) is not supported, but adding the diff --git a/lib/matplotlib/markers.py b/lib/matplotlib/markers.py index 2037a64f8d90..cf4634575f88 100644 --- a/lib/matplotlib/markers.py +++ b/lib/matplotlib/markers.py @@ -70,7 +70,7 @@ for `.Axes.scatter`). Note that special symbols can be defined via the -:doc:`STIX math font `, +:ref:`STIX math font `, e.g. ``"$\u266B$"``. For an overview over the STIX font symbols refer to the `STIX font table `_. Also see the :doc:`/gallery/text_labels_and_annotations/stix_fonts_demo`. diff --git a/lib/matplotlib/mathtext.py b/lib/matplotlib/mathtext.py index 276edf5c764e..e538d451f8dd 100644 --- a/lib/matplotlib/mathtext.py +++ b/lib/matplotlib/mathtext.py @@ -2,7 +2,7 @@ A module for parsing a subset of the TeX math syntax and rendering it to a Matplotlib backend. -For a tutorial of its usage, see :doc:`/tutorials/text/mathtext`. This +For a tutorial of its usage, see :ref:`mathtext`. This document is primarily concerned with implementation details. The module uses pyparsing_ to parse the TeX expression. diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc index bf3aab7949ff..8b7504731926 100644 --- a/lib/matplotlib/mpl-data/matplotlibrc +++ b/lib/matplotlib/mpl-data/matplotlibrc @@ -309,7 +309,7 @@ ## * LaTeX * ## *************************************************************************** ## For more information on LaTeX properties, see -## https://matplotlib.org/stable/tutorials/text/usetex.html +## https://matplotlib.org/stable/users/explain/text/usetex.html #text.usetex: False # use latex for all text handling. The following fonts # are supported through the usual rc parameter settings: # new century schoolbook, bookman, times, palatino, diff --git a/pyproject.toml b/pyproject.toml index 06da90b94a96..3d912bd5f9f0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -124,7 +124,7 @@ convention = "numpy" "galleries/tutorials/introductory/animation_tutorial.py" = ["E501"] "galleries/tutorials/introductory/images.py" = ["E501"] "galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] -"galleries/tutorials/text/annotations.py" = ["E402", "E501"] -"galleries/tutorials/text/mathtext.py" = ["E501"] -"galleries/tutorials/text/text_intro.py" = ["E402"] -"galleries/tutorials/text/text_props.py" = ["E501"] +"galleries/users_explain/text/annotations.py" = ["E402", "E501"] +"galleries/users_explain/text/mathtext.py" = ["E501"] +"galleries/users_explain/text/text_intro.py" = ["E402"] +"galleries/users_explain/text/text_props.py" = ["E501"] From e30f972c6f943935e3c0b3a65d18908038b18b42 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 08:44:38 -0800 Subject: [PATCH 09/23] DOC: move fonts.rst to py file --- galleries/users_explain/fonts.rst | 193 ------------------------ galleries/users_explain/text/fonts.py | 207 ++++++++++++++++++++++++++ 2 files changed, 207 insertions(+), 193 deletions(-) delete mode 100644 galleries/users_explain/fonts.rst create mode 100644 galleries/users_explain/text/fonts.py diff --git a/galleries/users_explain/fonts.rst b/galleries/users_explain/fonts.rst deleted file mode 100644 index 70c614a3c078..000000000000 --- a/galleries/users_explain/fonts.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. redirect-from:: /users/fonts - -Fonts in Matplotlib -=================== - -Matplotlib needs fonts to work with its text engine, some of which are shipped -alongside the installation. The default font is `DejaVu Sans -`_ which covers most European writing systems. -However, users can configure the default fonts, and provide their own custom -fonts. See :ref:`Customizing text properties ` for -details and :ref:`font-nonlatin` in particular for glyphs not supported by -DejaVu Sans. - -Matplotlib also provides an option to offload text rendering to a TeX engine -(``usetex=True``), see :ref:`Text rendering with LaTeX -`. - -Fonts in PDF and PostScript ---------------------------- - -Fonts have a long (and sometimes incompatible) history in computing, leading to -different platforms supporting different types of fonts. In practice, -Matplotlib supports three font specifications (in addition to pdf 'core fonts', -which are explained later in the guide): - -.. list-table:: Type of Fonts - :header-rows: 1 - - * - Type 1 (PDF) - - Type 3 (PDF/PS) - - TrueType (PDF) - * - One of the oldest types, introduced by Adobe - - Similar to Type 1 in terms of introduction - - Newer than previous types, used commonly today, introduced by Apple - * - Restricted subset of PostScript, charstrings are in bytecode - - Full PostScript language, allows embedding arbitrary code - (in theory, even render fractals when rasterizing!) - - Include a virtual machine that can execute code! - * - These fonts support font hinting - - Do not support font hinting - - Hinting supported (virtual machine processes the "hints") - * - Non-subsetted through Matplotlib - - Subsetted via external module ttconv - - Subsetted via external module `fontTools `__ - -.. note:: - - Adobe disabled__ support for authoring with Type 1 fonts in January 2023. - - __ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html - -Other font specifications which Matplotlib supports: - -- Type 42 fonts (PS): - - - PostScript wrapper around TrueType fonts - - 42 is the `Answer to Life, the Universe, and Everything! `_ - - Matplotlib uses the external library `fontTools `__ - to subset these types of fonts - -- OpenType fonts: - - - OpenType is a new standard for digital type fonts, developed jointly by - Adobe and Microsoft - - Generally contain a much larger character set! - - Limited support with Matplotlib - -Font subsetting -~~~~~~~~~~~~~~~ - -The PDF and PostScript formats support embedding fonts in files, allowing the -display program to correctly render the text, independent of what fonts are -installed on the viewer's computer and without the need to pre-rasterize the text. -This ensures that if the output is zoomed or resized the text does not become -pixelated. However, embedding full fonts in the file can lead to large output -files, particularly with fonts with many glyphs such as those that support CJK -(Chinese/Japanese/Korean). - -The solution to this problem is to subset the fonts used in the document and -only embed the glyphs actually used. This gets both vector text and small -files sizes. Computing the subset of the font required and writing the new -(reduced) font are both complex problem and thus Matplotlib relies on -`fontTools `__ and a vendored fork -of ttconv. - -Currently Type 3, Type 42, and TrueType fonts are subsetted. Type 1 fonts are not. - -Core Fonts -~~~~~~~~~~ - -In addition to the ability to embed fonts, as part of the `PostScript -`_ and `PDF -specification -`_ -there are 14 Core Fonts that compliant viewers must ensure are available. If -you restrict your document to only these fonts you do not have to embed any -font information in the document but still get vector text. - -This is especially helpful to generate *really lightweight* documents:: - - # trigger core fonts for PDF backend - plt.rcParams["pdf.use14corefonts"] = True - # trigger core fonts for PS backend - plt.rcParams["ps.useafm"] = True - - chars = "AFM ftw!" - fig, ax = plt.subplots() - ax.text(0.5, 0.5, chars) - - fig.savefig("AFM_PDF.pdf", format="pdf") - fig.savefig("AFM_PS.ps", format="ps) - -Fonts in SVG ------------- - -Text can output to SVG in two ways controlled by :rc:`svg.fonttype`: - -- as a path (``'path'``) in the SVG -- as string in the SVG with font styling on the element (``'none'``) - -When saving via ``'path'`` Matplotlib will compute the path of the glyphs used -as vector paths and write those to the output. The advantage of doing so is -that the SVG will look the same on all computers independent of what fonts are -installed. However the text will not be editable after the fact. -In contrast, saving with ``'none'`` will result in smaller files and the -text will appear directly in the markup. However, the appearance may vary -based on the SVG viewer and what fonts are available. - -Fonts in Agg ------------- - -To output text to raster formats via Agg, Matplotlib relies on `FreeType -`_. Because the exact rendering of the glyphs -changes between FreeType versions we pin to a specific version for our image -comparison tests. - -How Matplotlib selects fonts ----------------------------- - -Internally, using a font in Matplotlib is a three step process: - -1. a `.FontProperties` object is created (explicitly or implicitly) -2. based on the `.FontProperties` object the methods on `.FontManager` are used - to select the closest "best" font Matplotlib is aware of (except for - ``'none'`` mode of SVG). -3. the Python proxy for the font object is used by the backend code to render - the text -- the exact details depend on the backend via `.font_manager.get_font`. - -The algorithm to select the "best" font is a modified version of the algorithm -specified by the `CSS1 Specifications -`_ which is used by web browsers. -This algorithm takes into account the font family name (e.g. "Arial", "Noto -Sans CJK", "Hack", ...), the size, style, and weight. In addition to family -names that map directly to fonts there are five "generic font family names" -(serif, monospace, fantasy, cursive, and sans-serif) that will internally be -mapped to any one of a set of fonts. - -Currently the public API for doing step 2 is `.FontManager.findfont` (and that -method on the global `.FontManager` instance is aliased at the module level as -`.font_manager.findfont`), which will only find a single font and return the absolute -path to the font on the filesystem. - -Font fallback -------------- - -There is no font that covers the entire Unicode space thus it is possible for the -users to require a mix of glyphs that can not be satisfied from a single font. -While it has been possible to use multiple fonts within a Figure, on distinct -`.Text` instances, it was not previous possible to use multiple fonts in the -same `.Text` instance (as a web browser does). As of Matplotlib 3.6 the Agg, -SVG, PDF, and PS backends will "fallback" through multiple fonts in a single -`.Text` instance: - -.. plot:: - :include-source: - :caption: The string "There are 几个汉字 in between!" rendered with 2 fonts. - - fig, ax = plt.subplots() - ax.text( - .5, .5, "There are 几个汉字 in between!", - family=['DejaVu Sans', 'WenQuanYi Zen Hei'], - ha='center' - ) - -Internally this is implemented by setting The "font family" on -`.FontProperties` objects to a list of font families. A (currently) -private API extracts a list of paths to all of the fonts found and then -constructs a single `.ft2font.FT2Font` object that is aware of all of the fonts. -Each glyph of the string is rendered using the first font in the list that -contains that glyph. - -A majority of this work was done by Aitik Gupta supported by Google Summer of -Code 2021. diff --git a/galleries/users_explain/text/fonts.py b/galleries/users_explain/text/fonts.py new file mode 100644 index 000000000000..a74aaa8eeec8 --- /dev/null +++ b/galleries/users_explain/text/fonts.py @@ -0,0 +1,207 @@ +""" +.. redirect-from:: /users/fonts +.. redirect-from:: /users/explain/fonts + +.. _fonts: + +Fonts in Matplotlib +=================== + +Matplotlib needs fonts to work with its text engine, some of which are shipped +alongside the installation. The default font is `DejaVu Sans +`_ which covers most European writing systems. +However, users can configure the default fonts, and provide their own custom +fonts. See :ref:`Customizing text properties ` for +details and :ref:`font-nonlatin` in particular for glyphs not supported by +DejaVu Sans. + +Matplotlib also provides an option to offload text rendering to a TeX engine +(``usetex=True``), see :ref:`Text rendering with LaTeX `. +""" + +import matplotlib.pyplot as plt + +fig, ax = plt.subplots() +ax.text( + .5, .5, "There are 几个汉字 in between!", + family=['DejaVu Sans', 'WenQuanYi Zen Hei'], + ha='center' +) + + +# %% +# +# Fonts in PDF and PostScript +# --------------------------- +# +# Fonts have a long (and sometimes incompatible) history in computing, leading to +# different platforms supporting different types of fonts. In practice, +# Matplotlib supports three font specifications (in addition to pdf 'core fonts', +# which are explained later in the guide): +# +# .. list-table:: Type of Fonts +# :header-rows: 1 +# +# * - Type 1 (PDF) +# - Type 3 (PDF/PS) +# - TrueType (PDF) +# * - One of the oldest types, introduced by Adobe +# - Similar to Type 1 in terms of introduction +# - Newer than previous types, used commonly today, introduced by Apple +# * - Restricted subset of PostScript, charstrings are in bytecode +# - Full PostScript language, allows embedding arbitrary code +# (in theory, even render fractals when rasterizing!) +# - Include a virtual machine that can execute code! +# * - These fonts support font hinting +# - Do not support font hinting +# - Hinting supported (virtual machine processes the "hints") +# * - Non-subsetted through Matplotlib +# - Subsetted via external module ttconv +# - Subsetted via external module `fontTools `__ +# +# .. note:: +# +# Adobe disabled__ support for authoring with Type 1 fonts in January 2023. +# +# __ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html +# +# Other font specifications which Matplotlib supports: +# +# - Type 42 fonts (PS): +# +# - PostScript wrapper around TrueType fonts +# - 42 is the `Answer to Life, the Universe, and Everything! `_ +# - Matplotlib uses the external library `fontTools `__ +# to subset these types of fonts +# +# - OpenType fonts: +# +# - OpenType is a new standard for digital type fonts, developed jointly by +# Adobe and Microsoft +# - Generally contain a much larger character set! +# - Limited support with Matplotlib +# +# Font subsetting +# ~~~~~~~~~~~~~~~ +# +# The PDF and PostScript formats support embedding fonts in files, allowing the +# display program to correctly render the text, independent of what fonts are +# installed on the viewer's computer and without the need to pre-rasterize the text. +# This ensures that if the output is zoomed or resized the text does not become +# pixelated. However, embedding full fonts in the file can lead to large output +# files, particularly with fonts with many glyphs such as those that support CJK +# (Chinese/Japanese/Korean). +# +# The solution to this problem is to subset the fonts used in the document and +# only embed the glyphs actually used. This gets both vector text and small +# files sizes. Computing the subset of the font required and writing the new +# (reduced) font are both complex problem and thus Matplotlib relies on +# `fontTools `__ and a vendored fork +# of ttconv. +# +# Currently Type 3, Type 42, and TrueType fonts are subsetted. Type 1 fonts are not. +# +# Core Fonts +# ~~~~~~~~~~ +# +# In addition to the ability to embed fonts, as part of the `PostScript +# `_ and `PDF +# specification +# `_ +# there are 14 Core Fonts that compliant viewers must ensure are available. If +# you restrict your document to only these fonts you do not have to embed any +# font information in the document but still get vector text. +# +# This is especially helpful to generate *really lightweight* documents:: +# +# # trigger core fonts for PDF backend +# plt.rcParams["pdf.use14corefonts"] = True +# # trigger core fonts for PS backend +# plt.rcParams["ps.useafm"] = True +# +# chars = "AFM ftw!" +# fig, ax = plt.subplots() +# ax.text(0.5, 0.5, chars) +# +# fig.savefig("AFM_PDF.pdf", format="pdf") +# fig.savefig("AFM_PS.ps", format="ps) +# +# Fonts in SVG +# ------------ +# +# Text can output to SVG in two ways controlled by :rc:`svg.fonttype`: +# +# - as a path (``'path'``) in the SVG +# - as string in the SVG with font styling on the element (``'none'``) +# +# When saving via ``'path'`` Matplotlib will compute the path of the glyphs used +# as vector paths and write those to the output. The advantage of doing so is +# that the SVG will look the same on all computers independent of what fonts are +# installed. However the text will not be editable after the fact. +# In contrast, saving with ``'none'`` will result in smaller files and the +# text will appear directly in the markup. However, the appearance may vary +# based on the SVG viewer and what fonts are available. +# +# Fonts in Agg +# ------------ +# +# To output text to raster formats via Agg, Matplotlib relies on `FreeType +# `_. Because the exact rendering of the glyphs +# changes between FreeType versions we pin to a specific version for our image +# comparison tests. +# +# How Matplotlib selects fonts +# ---------------------------- +# +# Internally, using a font in Matplotlib is a three step process: +# +# 1. a `.FontProperties` object is created (explicitly or implicitly) +# 2. based on the `.FontProperties` object the methods on `.FontManager` are used +# to select the closest "best" font Matplotlib is aware of (except for +# ``'none'`` mode of SVG). +# 3. the Python proxy for the font object is used by the backend code to render +# the text -- the exact details depend on the backend via `.font_manager.get_font`. +# +# The algorithm to select the "best" font is a modified version of the algorithm +# specified by the `CSS1 Specifications +# `_ which is used by web browsers. +# This algorithm takes into account the font family name (e.g. "Arial", "Noto +# Sans CJK", "Hack", ...), the size, style, and weight. In addition to family +# names that map directly to fonts there are five "generic font family names" +# (serif, monospace, fantasy, cursive, and sans-serif) that will internally be +# mapped to any one of a set of fonts. +# +# Currently the public API for doing step 2 is `.FontManager.findfont` (and that +# method on the global `.FontManager` instance is aliased at the module level as +# `.font_manager.findfont`), which will only find a single font and return the absolute +# path to the font on the filesystem. +# +# Font fallback +# ------------- +# +# There is no font that covers the entire Unicode space thus it is possible for the +# users to require a mix of glyphs that can not be satisfied from a single font. +# While it has been possible to use multiple fonts within a Figure, on distinct +# `.Text` instances, it was not previous possible to use multiple fonts in the +# same `.Text` instance (as a web browser does). As of Matplotlib 3.6 the Agg, +# SVG, PDF, and PS backends will "fallback" through multiple fonts in a single +# `.Text` instance: +# + + fig, ax = plt.subplots() + ax.text( + .5, .5, "There are 几个汉字 in between!", + family=['DejaVu Sans', 'WenQuanYi Zen Hei'], + ha='center' + ) + +# %% +# Internally this is implemented by setting The "font family" on +# `.FontProperties` objects to a list of font families. A (currently) +# private API extracts a list of paths to all of the fonts found and then +# constructs a single `.ft2font.FT2Font` object that is aware of all of the fonts. +# Each glyph of the string is rendered using the first font in the list that +# contains that glyph. +# +# A majority of this work was done by Aitik Gupta supported by Google Summer of +# Code 2021. \ No newline at end of file From 92739dc14a56c081ff9299b0954ab345d9cb9e6d Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 10:05:04 -0800 Subject: [PATCH 10/23] DOC: Move animations --- .flake8 | 2 +- .../animation_tutorial.py => users_explain/animations.py} | 4 ++++ galleries/users_explain/axis/index.rst | 7 +++++++ galleries/users_explain/index.rst | 2 ++ pyproject.toml | 2 +- 5 files changed, 15 insertions(+), 2 deletions(-) rename galleries/{tutorials/introductory/animation_tutorial.py => users_explain/animations.py} (99%) create mode 100644 galleries/users_explain/axis/index.rst diff --git a/.flake8 b/.flake8 index ba0615439edc..4df5147e7f6b 100644 --- a/.flake8 +++ b/.flake8 @@ -64,7 +64,7 @@ per-file-ignores = galleries/users_explain/figure/constrainedlayout_guide.py: E402 galleries/tutorials/intermediate/legend_guide.py: E402 galleries/users_explain/figure/tight_layout_guide.py: E402 - galleries/tutorials/introductory/animation_tutorial.py: E501 + galleries/users_explain/animation_tutorial.py: E501 galleries/tutorials/introductory/images.py: E501 galleries/tutorials/introductory/pyplot.py: E402, E501 galleries/users_explain/text/annotations.py: E402, E501 diff --git a/galleries/tutorials/introductory/animation_tutorial.py b/galleries/users_explain/animations.py similarity index 99% rename from galleries/tutorials/introductory/animation_tutorial.py rename to galleries/users_explain/animations.py index 9b5754fb6e1b..b022350c8985 100644 --- a/galleries/tutorials/introductory/animation_tutorial.py +++ b/galleries/users_explain/animations.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/introductory/animation_tutorial + +.. _animations: + =========================== Animations using Matplotlib =========================== diff --git a/galleries/users_explain/axis/index.rst b/galleries/users_explain/axis/index.rst new file mode 100644 index 000000000000..22339261502c --- /dev/null +++ b/galleries/users_explain/axis/index.rst @@ -0,0 +1,7 @@ +.. _users_axis: + +Controlling and labelling Axis objects +-------------------------------------- + +Some good material in artist tutorial that should be cribbed from or used here. + diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index f4d6969e88c9..09d051d933e3 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -12,8 +12,10 @@ Using Matplotlib figure/index axes/index artists/index + axis/index colors/index text/index + animations backends.rst fonts.rst event_handling.rst diff --git a/pyproject.toml b/pyproject.toml index 3d912bd5f9f0..1ac08336f053 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -121,7 +121,7 @@ convention = "numpy" "galleries/users_explain/figure/constrainedlayout_guide.py" = ["E402"] "galleries/tutorials/intermediate/legend_guide.py" = ["E402"] "galleries/users_explain/figure/tight_layout_guide.py" = ["E402"] -"galleries/tutorials/introductory/animation_tutorial.py" = ["E501"] +"galleries/users_explain/animation_tutorial.py" = ["E501"] "galleries/tutorials/introductory/images.py" = ["E501"] "galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] "galleries/users_explain/text/annotations.py" = ["E402", "E501"] From 9626566fd1b170183a28736d50c9dc1b3c62cd1d Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 10:18:02 -0800 Subject: [PATCH 11/23] DOC: move backends --- galleries/users_explain/{ => figure}/backends.rst | 2 ++ galleries/users_explain/{ => figure}/event_handling.rst | 0 galleries/users_explain/figure/index.rst | 2 ++ .../users_explain/figure/writing_a_backend_pyplot_interface.rst | 2 +- galleries/users_explain/quick_start.py | 2 +- 5 files changed, 6 insertions(+), 2 deletions(-) rename galleries/users_explain/{ => figure}/backends.rst (99%) rename galleries/users_explain/{ => figure}/event_handling.rst (100%) diff --git a/galleries/users_explain/backends.rst b/galleries/users_explain/figure/backends.rst similarity index 99% rename from galleries/users_explain/backends.rst rename to galleries/users_explain/figure/backends.rst index 35be449d050e..d4d1ff8c0e38 100644 --- a/galleries/users_explain/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -1,3 +1,5 @@ +.. redirect_from:: /users/explain/backends + .. _backends: ======== diff --git a/galleries/users_explain/event_handling.rst b/galleries/users_explain/figure/event_handling.rst similarity index 100% rename from galleries/users_explain/event_handling.rst rename to galleries/users_explain/figure/event_handling.rst diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index 46b8a54d7e93..0b9ed9c35242 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -262,8 +262,10 @@ More reading .. toctree:: :maxdepth: 1 + Concept: Output backends Concept: Matplotlib Application Interfaces (APIs) In depth: Interacting with figures In depth: Interactive figures and asynchronous programming + In depth: Event handling In depth: Writing a backend -- the pyplot interface diff --git a/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst index 356bef65ec95..452f4d7610bb 100644 --- a/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst +++ b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst @@ -7,7 +7,7 @@ Writing a backend -- the pyplot interface ========================================= This page assumes general understanding of the information in the -:doc:`/users/explain/backends` page, and is instead intended as reference for +:ref:`backends` page, and is instead intended as reference for third-party backend implementers. It also only deals with the interaction between backends and `.pyplot`, not with the rendering side, which is described in `.backend_template`. diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index 7ed93c2ea1c5..3f658f0a8fce 100644 --- a/galleries/users_explain/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -68,7 +68,7 @@ # # It is often convenient to create the Axes together with the Figure, but you # can also manually add Axes later on. Note that many -# :doc:`Matplotlib backends ` support zooming and +# :ref:`Matplotlib backends ` support zooming and # panning on figure windows. # # For more on Figures, see :ref:`figure_explanation`. From 230fad3821e9219520f05ae394e5970a4ec5a718 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 10:22:13 -0800 Subject: [PATCH 12/23] DOC: move performance [ci doc] --- galleries/users_explain/artists/index.rst | 1 + galleries/users_explain/{ => artists}/performance.rst | 2 ++ 2 files changed, 3 insertions(+) rename galleries/users_explain/{ => artists}/performance.rst (99%) diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index 7f8dc7177577..429a0292739c 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -192,5 +192,6 @@ More details .. toctree:: :maxdepth: 1 + Concept: optimizing Artists for performance imshow_extent transforms_tutorial \ No newline at end of file diff --git a/galleries/users_explain/performance.rst b/galleries/users_explain/artists/performance.rst similarity index 99% rename from galleries/users_explain/performance.rst rename to galleries/users_explain/artists/performance.rst index 03bff404b7ab..d3e56e880031 100644 --- a/galleries/users_explain/performance.rst +++ b/galleries/users_explain/artists/performance.rst @@ -1,3 +1,5 @@ +.. redirect-from:: /users/explain/performance + .. _performance: Performance From 3af6a591a1cd129183e83d79c74a5d5fc7c98bd0 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 16:46:19 -0800 Subject: [PATCH 13/23] DOC: fixes [ci doc] --- galleries/users_explain/artists/index.rst | 2 +- galleries/users_explain/figure/backends.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index 429a0292739c..8e71deff8f22 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -193,5 +193,5 @@ More details :maxdepth: 1 Concept: optimizing Artists for performance - imshow_extent + In Depth: understanding the extent keyword argument of imshow transforms_tutorial \ No newline at end of file diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst index d4d1ff8c0e38..ae9266ef7f96 100644 --- a/galleries/users_explain/figure/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -1,4 +1,4 @@ -.. redirect_from:: /users/explain/backends +.. redirect-from:: /users/explain/backends .. _backends: From 0a43f82fa8b76dcb94d9aa2477c7cc1e2e153fe7 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 16:59:24 -0800 Subject: [PATCH 14/23] DOC: Fix fonts [ci doc] --- galleries/users_explain/text/fonts.py | 367 +++++++++++++------------- 1 file changed, 179 insertions(+), 188 deletions(-) diff --git a/galleries/users_explain/text/fonts.py b/galleries/users_explain/text/fonts.py index a74aaa8eeec8..d703c85f989d 100644 --- a/galleries/users_explain/text/fonts.py +++ b/galleries/users_explain/text/fonts.py @@ -1,4 +1,4 @@ -""" +r""" .. redirect-from:: /users/fonts .. redirect-from:: /users/explain/fonts @@ -16,192 +16,183 @@ DejaVu Sans. Matplotlib also provides an option to offload text rendering to a TeX engine -(``usetex=True``), see :ref:`Text rendering with LaTeX `. -""" - -import matplotlib.pyplot as plt - -fig, ax = plt.subplots() -ax.text( - .5, .5, "There are 几个汉字 in between!", - family=['DejaVu Sans', 'WenQuanYi Zen Hei'], - ha='center' -) - - -# %% -# -# Fonts in PDF and PostScript -# --------------------------- -# -# Fonts have a long (and sometimes incompatible) history in computing, leading to -# different platforms supporting different types of fonts. In practice, -# Matplotlib supports three font specifications (in addition to pdf 'core fonts', -# which are explained later in the guide): -# -# .. list-table:: Type of Fonts -# :header-rows: 1 -# -# * - Type 1 (PDF) -# - Type 3 (PDF/PS) -# - TrueType (PDF) -# * - One of the oldest types, introduced by Adobe -# - Similar to Type 1 in terms of introduction -# - Newer than previous types, used commonly today, introduced by Apple -# * - Restricted subset of PostScript, charstrings are in bytecode -# - Full PostScript language, allows embedding arbitrary code -# (in theory, even render fractals when rasterizing!) -# - Include a virtual machine that can execute code! -# * - These fonts support font hinting -# - Do not support font hinting -# - Hinting supported (virtual machine processes the "hints") -# * - Non-subsetted through Matplotlib -# - Subsetted via external module ttconv -# - Subsetted via external module `fontTools `__ -# -# .. note:: -# -# Adobe disabled__ support for authoring with Type 1 fonts in January 2023. -# -# __ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html -# -# Other font specifications which Matplotlib supports: -# -# - Type 42 fonts (PS): -# -# - PostScript wrapper around TrueType fonts -# - 42 is the `Answer to Life, the Universe, and Everything! `_ -# - Matplotlib uses the external library `fontTools `__ -# to subset these types of fonts -# -# - OpenType fonts: -# -# - OpenType is a new standard for digital type fonts, developed jointly by -# Adobe and Microsoft -# - Generally contain a much larger character set! -# - Limited support with Matplotlib -# -# Font subsetting -# ~~~~~~~~~~~~~~~ -# -# The PDF and PostScript formats support embedding fonts in files, allowing the -# display program to correctly render the text, independent of what fonts are -# installed on the viewer's computer and without the need to pre-rasterize the text. -# This ensures that if the output is zoomed or resized the text does not become -# pixelated. However, embedding full fonts in the file can lead to large output -# files, particularly with fonts with many glyphs such as those that support CJK -# (Chinese/Japanese/Korean). -# -# The solution to this problem is to subset the fonts used in the document and -# only embed the glyphs actually used. This gets both vector text and small -# files sizes. Computing the subset of the font required and writing the new -# (reduced) font are both complex problem and thus Matplotlib relies on -# `fontTools `__ and a vendored fork -# of ttconv. -# -# Currently Type 3, Type 42, and TrueType fonts are subsetted. Type 1 fonts are not. -# -# Core Fonts -# ~~~~~~~~~~ -# -# In addition to the ability to embed fonts, as part of the `PostScript -# `_ and `PDF -# specification -# `_ -# there are 14 Core Fonts that compliant viewers must ensure are available. If -# you restrict your document to only these fonts you do not have to embed any -# font information in the document but still get vector text. -# -# This is especially helpful to generate *really lightweight* documents:: -# -# # trigger core fonts for PDF backend -# plt.rcParams["pdf.use14corefonts"] = True -# # trigger core fonts for PS backend -# plt.rcParams["ps.useafm"] = True -# -# chars = "AFM ftw!" -# fig, ax = plt.subplots() -# ax.text(0.5, 0.5, chars) -# -# fig.savefig("AFM_PDF.pdf", format="pdf") -# fig.savefig("AFM_PS.ps", format="ps) -# -# Fonts in SVG -# ------------ -# -# Text can output to SVG in two ways controlled by :rc:`svg.fonttype`: -# -# - as a path (``'path'``) in the SVG -# - as string in the SVG with font styling on the element (``'none'``) -# -# When saving via ``'path'`` Matplotlib will compute the path of the glyphs used -# as vector paths and write those to the output. The advantage of doing so is -# that the SVG will look the same on all computers independent of what fonts are -# installed. However the text will not be editable after the fact. -# In contrast, saving with ``'none'`` will result in smaller files and the -# text will appear directly in the markup. However, the appearance may vary -# based on the SVG viewer and what fonts are available. -# -# Fonts in Agg -# ------------ -# -# To output text to raster formats via Agg, Matplotlib relies on `FreeType -# `_. Because the exact rendering of the glyphs -# changes between FreeType versions we pin to a specific version for our image -# comparison tests. -# -# How Matplotlib selects fonts -# ---------------------------- -# -# Internally, using a font in Matplotlib is a three step process: -# -# 1. a `.FontProperties` object is created (explicitly or implicitly) -# 2. based on the `.FontProperties` object the methods on `.FontManager` are used -# to select the closest "best" font Matplotlib is aware of (except for -# ``'none'`` mode of SVG). -# 3. the Python proxy for the font object is used by the backend code to render -# the text -- the exact details depend on the backend via `.font_manager.get_font`. -# -# The algorithm to select the "best" font is a modified version of the algorithm -# specified by the `CSS1 Specifications -# `_ which is used by web browsers. -# This algorithm takes into account the font family name (e.g. "Arial", "Noto -# Sans CJK", "Hack", ...), the size, style, and weight. In addition to family -# names that map directly to fonts there are five "generic font family names" -# (serif, monospace, fantasy, cursive, and sans-serif) that will internally be -# mapped to any one of a set of fonts. -# -# Currently the public API for doing step 2 is `.FontManager.findfont` (and that -# method on the global `.FontManager` instance is aliased at the module level as -# `.font_manager.findfont`), which will only find a single font and return the absolute -# path to the font on the filesystem. -# -# Font fallback -# ------------- -# -# There is no font that covers the entire Unicode space thus it is possible for the -# users to require a mix of glyphs that can not be satisfied from a single font. -# While it has been possible to use multiple fonts within a Figure, on distinct -# `.Text` instances, it was not previous possible to use multiple fonts in the -# same `.Text` instance (as a web browser does). As of Matplotlib 3.6 the Agg, -# SVG, PDF, and PS backends will "fallback" through multiple fonts in a single -# `.Text` instance: -# +(``usetex=True``), see :ref:`Text rendering with LaTeX +`. +Fonts in PDF and PostScript +--------------------------- + +Fonts have a long (and sometimes incompatible) history in computing, leading to +different platforms supporting different types of fonts. In practice, +Matplotlib supports three font specifications (in addition to pdf 'core fonts', +which are explained later in the guide): + +.. list-table:: Type of Fonts + :header-rows: 1 + + * - Type 1 (PDF) + - Type 3 (PDF/PS) + - TrueType (PDF) + * - One of the oldest types, introduced by Adobe + - Similar to Type 1 in terms of introduction + - Newer than previous types, used commonly today, introduced by Apple + * - Restricted subset of PostScript, charstrings are in bytecode + - Full PostScript language, allows embedding arbitrary code + (in theory, even render fractals when rasterizing!) + - Include a virtual machine that can execute code! + * - These fonts support font hinting + - Do not support font hinting + - Hinting supported (virtual machine processes the "hints") + * - Non-subsetted through Matplotlib + - Subsetted via external module ttconv + - Subsetted via external module `fontTools `__ + +.. note:: + + Adobe disabled__ support for authoring with Type 1 fonts in January 2023. + + __ https://helpx.adobe.com/fonts/kb/postscript-type-1-fonts-end-of-support.html + +Other font specifications which Matplotlib supports: + +- Type 42 fonts (PS): + + - PostScript wrapper around TrueType fonts + - 42 is the `Answer to Life, the Universe, and Everything! `_ + - Matplotlib uses the external library `fontTools `__ + to subset these types of fonts + +- OpenType fonts: + + - OpenType is a new standard for digital type fonts, developed jointly by + Adobe and Microsoft + - Generally contain a much larger character set! + - Limited support with Matplotlib + +Font subsetting +~~~~~~~~~~~~~~~ + +The PDF and PostScript formats support embedding fonts in files, allowing the +display program to correctly render the text, independent of what fonts are +installed on the viewer's computer and without the need to pre-rasterize the text. +This ensures that if the output is zoomed or resized the text does not become +pixelated. However, embedding full fonts in the file can lead to large output +files, particularly with fonts with many glyphs such as those that support CJK +(Chinese/Japanese/Korean). + +The solution to this problem is to subset the fonts used in the document and +only embed the glyphs actually used. This gets both vector text and small +files sizes. Computing the subset of the font required and writing the new +(reduced) font are both complex problem and thus Matplotlib relies on +`fontTools `__ and a vendored fork +of ttconv. + +Currently Type 3, Type 42, and TrueType fonts are subsetted. Type 1 fonts are not. + +Core Fonts +~~~~~~~~~~ + +In addition to the ability to embed fonts, as part of the `PostScript +`_ and `PDF +specification +`_ +there are 14 Core Fonts that compliant viewers must ensure are available. If +you restrict your document to only these fonts you do not have to embed any +font information in the document but still get vector text. + +This is especially helpful to generate *really lightweight* documents:: + + # trigger core fonts for PDF backend + plt.rcParams["pdf.use14corefonts"] = True + # trigger core fonts for PS backend + plt.rcParams["ps.useafm"] = True + + chars = "AFM ftw!" fig, ax = plt.subplots() - ax.text( - .5, .5, "There are 几个汉字 in between!", - family=['DejaVu Sans', 'WenQuanYi Zen Hei'], - ha='center' - ) - -# %% -# Internally this is implemented by setting The "font family" on -# `.FontProperties` objects to a list of font families. A (currently) -# private API extracts a list of paths to all of the fonts found and then -# constructs a single `.ft2font.FT2Font` object that is aware of all of the fonts. -# Each glyph of the string is rendered using the first font in the list that -# contains that glyph. -# -# A majority of this work was done by Aitik Gupta supported by Google Summer of -# Code 2021. \ No newline at end of file + ax.text(0.5, 0.5, chars) + + fig.savefig("AFM_PDF.pdf", format="pdf") + fig.savefig("AFM_PS.ps", format="ps) + +Fonts in SVG +------------ + +Text can output to SVG in two ways controlled by :rc:`svg.fonttype`: + +- as a path (``'path'``) in the SVG +- as string in the SVG with font styling on the element (``'none'``) + +When saving via ``'path'`` Matplotlib will compute the path of the glyphs used +as vector paths and write those to the output. The advantage of doing so is +that the SVG will look the same on all computers independent of what fonts are +installed. However the text will not be editable after the fact. +In contrast, saving with ``'none'`` will result in smaller files and the +text will appear directly in the markup. However, the appearance may vary +based on the SVG viewer and what fonts are available. + +Fonts in Agg +------------ + +To output text to raster formats via Agg, Matplotlib relies on `FreeType +`_. Because the exact rendering of the glyphs +changes between FreeType versions we pin to a specific version for our image +comparison tests. + +How Matplotlib selects fonts +---------------------------- + +Internally, using a font in Matplotlib is a three step process: + +1. a `.FontProperties` object is created (explicitly or implicitly) +2. based on the `.FontProperties` object the methods on `.FontManager` are used + to select the closest "best" font Matplotlib is aware of (except for + ``'none'`` mode of SVG). +3. the Python proxy for the font object is used by the backend code to render + the text -- the exact details depend on the backend via `.font_manager.get_font`. + +The algorithm to select the "best" font is a modified version of the algorithm +specified by the `CSS1 Specifications +`_ which is used by web browsers. +This algorithm takes into account the font family name (e.g. "Arial", "Noto +Sans CJK", "Hack", ...), the size, style, and weight. In addition to family +names that map directly to fonts there are five "generic font family names" +(serif, monospace, fantasy, cursive, and sans-serif) that will internally be +mapped to any one of a set of fonts. + +Currently the public API for doing step 2 is `.FontManager.findfont` (and that +method on the global `.FontManager` instance is aliased at the module level as +`.font_manager.findfont`), which will only find a single font and return the absolute +path to the font on the filesystem. + +Font fallback +------------- + +There is no font that covers the entire Unicode space thus it is possible for the +users to require a mix of glyphs that can not be satisfied from a single font. +While it has been possible to use multiple fonts within a Figure, on distinct +`.Text` instances, it was not previous possible to use multiple fonts in the +same `.Text` instance (as a web browser does). As of Matplotlib 3.6 the Agg, +SVG, PDF, and PS backends will "fallback" through multiple fonts in a single +`.Text` instance: + +.. plot:: + :include-source: + :caption: The string "There are 几个汉字 in between!" rendered with 2 fonts. + + fig, ax = plt.subplots() + ax.text( + .5, .5, "There are 几个汉字 in between!", + family=['DejaVu Sans', 'WenQuanYi Zen Hei'], + ha='center' + ) + +Internally this is implemented by setting The "font family" on +`.FontProperties` objects to a list of font families. A (currently) +private API extracts a list of paths to all of the fonts found and then +constructs a single `.ft2font.FT2Font` object that is aware of all of the fonts. +Each glyph of the string is rendered using the first font in the list that +contains that glyph. + +A majority of this work was done by Aitik Gupta supported by Google Summer of +Code 2021. +""" \ No newline at end of file From a1bcf87ab67a035c1d5041daf2ce06b8e6406079 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 20:28:05 -0800 Subject: [PATCH 15/23] DOC: move autoscale --- doc/api/style_api.rst | 2 +- doc/devel/documenting_mpl.rst | 7 +++---- doc/users/faq/troubleshooting_faq.rst | 2 +- doc/users/installing/index.rst | 2 +- doc/users/prev_whats_new/whats_new_3.4.0.rst | 4 ++-- galleries/examples/color/color_cycle_default.py | 2 +- galleries/tutorials/introductory/lifecycle.py | 2 +- galleries/users_explain/artists/performance.rst | 4 ++-- .../intermediate => users_explain/axes}/autoscale.py | 4 ++++ galleries/users_explain/axes/index.rst | 6 ++++-- .../introductory => users_explain}/customizing.py | 3 +++ galleries/users_explain/figure/backends.rst | 2 +- galleries/users_explain/figure/index.rst | 2 +- galleries/users_explain/figure/interactive.rst | 4 ++-- galleries/users_explain/index.rst | 5 +---- galleries/users_explain/text/mathtext.py | 2 +- galleries/users_explain/text/text_intro.py | 2 +- galleries/users_explain/text/text_props.py | 2 +- galleries/users_explain/text/usetex.py | 3 +-- lib/matplotlib/mpl-data/matplotlibrc | 2 +- 20 files changed, 33 insertions(+), 29 deletions(-) rename galleries/{tutorials/intermediate => users_explain/axes}/autoscale.py (98%) rename galleries/{tutorials/introductory => users_explain}/customizing.py (99%) diff --git a/doc/api/style_api.rst b/doc/api/style_api.rst index 84bbe8b25c84..1f124965da61 100644 --- a/doc/api/style_api.rst +++ b/doc/api/style_api.rst @@ -5,7 +5,7 @@ Styles are predefined sets of `.rcParams` that define the visual appearance of a plot. -:doc:`/tutorials/introductory/customizing` describes the mechanism and usage +:ref:`customizing` describes the mechanism and usage of styles. The :doc:`/gallery/style_sheets/style_sheets_reference` gives an overview of diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index a3090a6249a6..37a7bb4ba9f7 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -858,10 +858,9 @@ The first comment block is treated as ReST_ text. The other comment blocks render as comments in :doc:`/gallery/lines_bars_and_markers/simple_plot`. Tutorials are made with the exact same mechanism, except they are longer, and -typically have more than one comment block (i.e. -:ref:`quick_start`). The first comment block -can be the same as the example above. Subsequent blocks of ReST text are -delimited by the line ``# %%`` : +typically have more than one comment block (i.e. :ref:`quick_start`). The +first comment block can be the same as the example above. Subsequent blocks of +ReST text are delimited by the line ``# %%`` : .. code-block:: python diff --git a/doc/users/faq/troubleshooting_faq.rst b/doc/users/faq/troubleshooting_faq.rst index f88cb19d1395..8deb7f02ae32 100644 --- a/doc/users/faq/troubleshooting_faq.rst +++ b/doc/users/faq/troubleshooting_faq.rst @@ -106,7 +106,7 @@ provide the following information in your e-mail to the `mailing list GitHub, PyPI, or `Anaconda `_). * Any customizations to your ``matplotlibrc`` file (see - :doc:`/tutorials/introductory/customizing`). + :ref:`customizing`). * If the problem is reproducible, please try to provide a *minimal*, standalone Python script that demonstrates the problem. This is *the* critical step. diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst index 1b6fdf65055f..f91ee8f94e96 100644 --- a/doc/users/installing/index.rst +++ b/doc/users/installing/index.rst @@ -219,7 +219,7 @@ example:: This will give you additional information about which backends Matplotlib is loading, version information, and more. At this point you might want to make -sure you understand Matplotlib's :doc:`configuration ` +sure you understand Matplotlib's :ref:`configuration ` process, governed by the :file:`matplotlibrc` configuration file which contains instructions within and the concept of the Matplotlib backend. diff --git a/doc/users/prev_whats_new/whats_new_3.4.0.rst b/doc/users/prev_whats_new/whats_new_3.4.0.rst index 6e9a3a82cf08..f90a95c7f126 100644 --- a/doc/users/prev_whats_new/whats_new_3.4.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.4.0.rst @@ -617,8 +617,8 @@ forward and inverse. size=16, va='center', ha='center') plt.show() -See :ref:`colormapnorms` for an example and more details -about data normalization. +See :ref:`colormapnorms` for an example and more details about data +normalization. GridSpec-based colorbars can now be positioned above or to the left of the main axes ------------------------------------------------------------------------------------ diff --git a/galleries/examples/color/color_cycle_default.py b/galleries/examples/color/color_cycle_default.py index ea81aa4fb1e6..a41ff5f63ff8 100644 --- a/galleries/examples/color/color_cycle_default.py +++ b/galleries/examples/color/color_cycle_default.py @@ -4,7 +4,7 @@ ==================================== Display the colors from the default prop_cycle, which is obtained from the -:doc:`rc parameters`. +:ref:`rc parameters`. """ import matplotlib.pyplot as plt import numpy as np diff --git a/galleries/tutorials/introductory/lifecycle.py b/galleries/tutorials/introductory/lifecycle.py index a881ff903c68..5613d52cb2ea 100644 --- a/galleries/tutorials/introductory/lifecycle.py +++ b/galleries/tutorials/introductory/lifecycle.py @@ -149,7 +149,7 @@ # that we create. To do this we set the ``autolayout`` value of our # rcParams. For more information on controlling the style, layout, and # other features of plots with rcParams, see -# :doc:`/tutorials/introductory/customizing`. +# :ref:`customizing`. plt.rcParams.update({'figure.autolayout': True}) diff --git a/galleries/users_explain/artists/performance.rst b/galleries/users_explain/artists/performance.rst index d3e56e880031..20ac800abad6 100644 --- a/galleries/users_explain/artists/performance.rst +++ b/galleries/users_explain/artists/performance.rst @@ -20,7 +20,7 @@ For plots that have line segments (e.g. typical line plots, outlines of polygons, etc.), rendering performance can be controlled by :rc:`path.simplify` and :rc:`path.simplify_threshold`, which can be defined e.g. in the :file:`matplotlibrc` file (see -:doc:`/tutorials/introductory/customizing` for more information about +:ref:`customizing` for more information about the :file:`matplotlibrc` file). :rc:`path.simplify` is a Boolean indicating whether or not line segments are simplified at all. :rc:`path.simplify_threshold` controls how much line segments are simplified; @@ -54,7 +54,7 @@ value, change the :file:`matplotlibrc` file. Alternatively, users can create a new style for interactive plotting (with maximal simplification) and another style for publication quality plotting (with minimal simplification) and activate them as necessary. See -:doc:`/tutorials/introductory/customizing` for instructions on +:ref:`customizing` for instructions on how to perform these actions. The simplification works by iteratively merging line segments diff --git a/galleries/tutorials/intermediate/autoscale.py b/galleries/users_explain/axes/autoscale.py similarity index 98% rename from galleries/tutorials/intermediate/autoscale.py rename to galleries/users_explain/axes/autoscale.py index 95a157548804..fef68f2515d9 100644 --- a/galleries/tutorials/intermediate/autoscale.py +++ b/galleries/users_explain/axes/autoscale.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/autoscale + +.. _autoscale: + Autoscaling =========== diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 4c616f06ec46..edd6b6de50b9 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -70,7 +70,9 @@ Figure. Axes plotting methods --------------------- -Most of the high-level plotting methods are accessed from the `.axes.Axes` class. See the API documentation for a full curated list, and :ref:`plot_types` for examples. A basic example is `.axes.Axes.plot`: +Most of the high-level plotting methods are accessed from the `.axes.Axes` +class. See the API documentation for a full curated list, and +:ref:`plot_types` for examples. A basic example is `.axes.Axes.plot`: .. plot:: :include-source: @@ -147,7 +149,6 @@ The Axes class also has helpers to deal with Axis ticks and their labels. Most Setting scales and controlling the Axis can be highly customized beyond these Axes-level helpers. An introduction to these methods can be found in :ref:`users_axis`, or the API reference for `.axis.Axis`. - Axes layout ----------- @@ -172,6 +173,7 @@ Sometimes it is important to set the aspect ratio of a plot in data space, which arranging_axes colorbar_placement + In depth: autoscaling axes In depth: subplot mosaic In depth: Constrained layout guide In depth: Tight layout guide (mildly discouraged) diff --git a/galleries/tutorials/introductory/customizing.py b/galleries/users_explain/customizing.py similarity index 99% rename from galleries/tutorials/introductory/customizing.py rename to galleries/users_explain/customizing.py index 4de4246f6eb9..58eccbcfa960 100644 --- a/galleries/tutorials/introductory/customizing.py +++ b/galleries/users_explain/customizing.py @@ -1,5 +1,8 @@ """ .. redirect-from:: /users/customizing +.. redirect-from:: /tutorials/introductory/customizing + +.. _customizing: ===================================================== Customizing Matplotlib with style sheets and rcParams diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst index ae9266ef7f96..c810c3ce30e6 100644 --- a/galleries/users_explain/figure/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -61,7 +61,7 @@ Here is a detailed description of the configuration methods: backend : qtagg # use pyqt with antigrain (agg) rendering - See also :doc:`/tutorials/introductory/customizing`. + See also :ref:`customizing`. #. Setting the :envvar:`MPLBACKEND` environment variable: diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index 0b9ed9c35242..a3420f47aabb 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -266,6 +266,6 @@ More reading Concept: Matplotlib Application Interfaces (APIs) In depth: Interacting with figures In depth: Interactive figures and asynchronous programming - In depth: Event handling + In depth: Event handling In depth: Writing a backend -- the pyplot interface diff --git a/galleries/users_explain/figure/interactive.rst b/galleries/users_explain/figure/interactive.rst index a710435886ed..3b64398e2b3e 100644 --- a/galleries/users_explain/figure/interactive.rst +++ b/galleries/users_explain/figure/interactive.rst @@ -211,8 +211,8 @@ Navigation keyboard shortcuts ----------------------------- The following table holds all the default keys, which can be -overwritten by use of your :doc:`matplotlibrc -`. +overwritten by use of your :ref:`matplotlibrc +`. ================================== =============================== Command Default key binding and rcParam diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 09d051d933e3..f466b4ca0ddf 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -12,11 +12,8 @@ Using Matplotlib figure/index axes/index artists/index + customizing axis/index colors/index text/index animations - backends.rst - fonts.rst - event_handling.rst - performance.rst diff --git a/galleries/users_explain/text/mathtext.py b/galleries/users_explain/text/mathtext.py index b0812c67b221..211d46dd50b9 100644 --- a/galleries/users_explain/text/mathtext.py +++ b/galleries/users_explain/text/mathtext.py @@ -24,7 +24,7 @@ (from (La)TeX), `STIX `_ fonts (which are designed to blend well with Times), or a Unicode font that you provide. The mathtext font can be selected via :rc:`mathtext.fontset` (see -:doc:`/tutorials/introductory/customizing`) +:ref:`customizing`) Here is a simple example:: diff --git a/galleries/users_explain/text/text_intro.py b/galleries/users_explain/text/text_intro.py index 628531babdf4..efca26c1b813 100644 --- a/galleries/users_explain/text/text_intro.py +++ b/galleries/users_explain/text/text_intro.py @@ -26,7 +26,7 @@ The user has a great deal of control over text properties (font size, font weight, text location and color, etc.) with sensible defaults set in -the :doc:`rc file `. +the :ref:`rc file `. And significantly, for those interested in mathematical or scientific figures, Matplotlib implements a large number of TeX math symbols and commands, supporting :ref:`mathematical expressions diff --git a/galleries/users_explain/text/text_props.py b/galleries/users_explain/text/text_props.py index 955197e37f02..20111f0775f5 100644 --- a/galleries/users_explain/text/text_props.py +++ b/galleries/users_explain/text/text_props.py @@ -191,7 +191,7 @@ # matplotlib.font_manager.get_font_names() # # The mapping between the generic family aliases and actual font families -# (mentioned at :doc:`default rcParams `) +# (mentioned at :ref:`default rcParams `) # is controlled by the following rcParams: # # diff --git a/galleries/users_explain/text/usetex.py b/galleries/users_explain/text/usetex.py index 97578c8b9380..0194a0030d48 100644 --- a/galleries/users_explain/text/usetex.py +++ b/galleries/users_explain/text/usetex.py @@ -55,8 +55,7 @@ "font.family": "Helvetica" }) -or equivalently, set your :doc:`matplotlibrc -` to:: +or equivalently, set your :ref:`matplotlibrc ` to:: text.usetex : true font.family : Helvetica diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc index 8b7504731926..b2901d0bde11 100644 --- a/lib/matplotlib/mpl-data/matplotlibrc +++ b/lib/matplotlib/mpl-data/matplotlibrc @@ -16,7 +16,7 @@ ## $HOME/.matplotlib/matplotlibrc ## and edit that copy. ## -## See https://matplotlib.org/stable/tutorials/introductory/customizing.html#customizing-with-matplotlibrc-files +## See https://matplotlib.org/stable/users/explain/customizing.html#customizing-with-matplotlibrc-files ## for more details on the paths which are checked for the configuration file. ## ## Blank lines, or lines starting with a comment symbol, are ignored, as are From 63bf0afb6b0e00d61e7846991ab4a8d943a633e7 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 20:34:59 -0800 Subject: [PATCH 16/23] DOC: move legend_guide --- .flake8 | 2 +- doc/api/prev_api_changes/api_changes_1.4.x.rst | 2 +- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/prev_whats_new/whats_new_1.1.rst | 2 +- doc/users/prev_whats_new/whats_new_1.4.rst | 2 +- doc/users/prev_whats_new/whats_new_3.7.0.rst | 2 +- .../text_labels_and_annotations/custom_legends.py | 2 +- galleries/users_explain/axes/index.rst | 5 +++-- .../axes}/legend_guide.py | 3 ++- galleries/users_explain/quick_start.py | 2 +- galleries/users_explain/text/text_intro.py | 2 +- lib/matplotlib/axes/_axes.py | 2 +- lib/matplotlib/figure.py | 2 +- lib/matplotlib/legend.py | 10 +++++----- lib/matplotlib/legend_handler.py | 4 ++-- pyproject.toml | 2 +- 16 files changed, 24 insertions(+), 22 deletions(-) rename galleries/{tutorials/intermediate => users_explain/axes}/legend_guide.py (99%) diff --git a/.flake8 b/.flake8 index 4df5147e7f6b..311d1508fa1d 100644 --- a/.flake8 +++ b/.flake8 @@ -62,7 +62,7 @@ per-file-ignores = galleries/users_explain/colors/colors.py: E402 galleries/tutorials/intermediate/artists.py: E402 galleries/users_explain/figure/constrainedlayout_guide.py: E402 - galleries/tutorials/intermediate/legend_guide.py: E402 + galleries/users_explain/axes/legend_guide.py: E402 galleries/users_explain/figure/tight_layout_guide.py: E402 galleries/users_explain/animation_tutorial.py: E501 galleries/tutorials/introductory/images.py: E501 diff --git a/doc/api/prev_api_changes/api_changes_1.4.x.rst b/doc/api/prev_api_changes/api_changes_1.4.x.rst index c12d40a67991..9f2436a81df7 100644 --- a/doc/api/prev_api_changes/api_changes_1.4.x.rst +++ b/doc/api/prev_api_changes/api_changes_1.4.x.rst @@ -88,7 +88,7 @@ original location: * The legend handler interface has changed from a callable, to any object which implements the ``legend_artists`` method (a deprecation phase will see this interface be maintained for v1.4). See - :doc:`/tutorials/intermediate/legend_guide` for further details. Further legend changes + :ref:`legend_guide` for further details. Further legend changes include: * ``matplotlib.axes.Axes._get_legend_handles`` now returns a generator of diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index 04156de65e9c..0abf98ed8f8c 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -11,7 +11,7 @@ What's new in Matplotlib 0.99 (Aug 29, 2009) New documentation ----------------- -Jae-Joon Lee has written two new guides :doc:`/tutorials/intermediate/legend_guide` +Jae-Joon Lee has written two new guides :ref:`legend_guide` and :ref:`plotting-guide-annotation`. Michael Sarahan has written :doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst index a2c0ebf2045c..59a53ca3c801 100644 --- a/doc/users/prev_whats_new/whats_new_1.1.rst +++ b/doc/users/prev_whats_new/whats_new_1.1.rst @@ -114,7 +114,7 @@ legends for complex plots such as :meth:`~matplotlib.pyplot.stem` plots will now display correctly. Second, the 'best' placement of a legend has been improved in the presence of NANs. -See the :doc:`/tutorials/intermediate/legend_guide` for more detailed explanation and +See the :ref:`legend_guide` for more detailed explanation and examples. .. figure:: ../../gallery/text_labels_and_annotations/images/sphx_glr_legend_demo_004.png diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst index 057f547c9f4c..b3ecf939b589 100644 --- a/doc/users/prev_whats_new/whats_new_1.4.rst +++ b/doc/users/prev_whats_new/whats_new_1.4.rst @@ -406,7 +406,7 @@ instead of ``:context:`` any time you want to reset the context. Legend and PathEffects documentation ------------------------------------ -The :doc:`/tutorials/intermediate/legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been +The :ref:`legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been updated to better reflect the full potential of each of these powerful features. diff --git a/doc/users/prev_whats_new/whats_new_3.7.0.rst b/doc/users/prev_whats_new/whats_new_3.7.0.rst index 37991f79c508..5595e142a337 100644 --- a/doc/users/prev_whats_new/whats_new_3.7.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.7.0.rst @@ -336,7 +336,7 @@ by a *loc* keyword argument that starts with the string "outside". The codes are unique from axes codes, in that "outside upper right" will make room at the top of the figure for the legend, whereas "outside right upper" will make room on the right-hand side of the figure. -See :doc:`/tutorials/intermediate/legend_guide` for details. +See :ref:`legend_guide` for details. Per-subplot keyword arguments in ``subplot_mosaic`` diff --git a/galleries/examples/text_labels_and_annotations/custom_legends.py b/galleries/examples/text_labels_and_annotations/custom_legends.py index 62965a455d61..f1714a21a481 100644 --- a/galleries/examples/text_labels_and_annotations/custom_legends.py +++ b/galleries/examples/text_labels_and_annotations/custom_legends.py @@ -10,7 +10,7 @@ For more information on creating and customizing legends, see the following pages: - * :doc:`/tutorials/intermediate/legend_guide` + * :ref:`legend_guide` * :doc:`/gallery/text_labels_and_annotations/legend_demo` Sometimes you don't want a legend that is explicitly tied to data that diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index edd6b6de50b9..54583212cb40 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -173,7 +173,8 @@ Sometimes it is important to set the aspect ratio of a plot in data space, which arranging_axes colorbar_placement - In depth: autoscaling axes - In depth: subplot mosaic + In depth: Autoscaling axes + In depth: Legends + In depth: Subplot mosaic In depth: Constrained layout guide In depth: Tight layout guide (mildly discouraged) diff --git a/galleries/tutorials/intermediate/legend_guide.py b/galleries/users_explain/axes/legend_guide.py similarity index 99% rename from galleries/tutorials/intermediate/legend_guide.py rename to galleries/users_explain/axes/legend_guide.py index cca977ccf018..48304e4a217c 100644 --- a/galleries/tutorials/intermediate/legend_guide.py +++ b/galleries/users_explain/axes/legend_guide.py @@ -1,4 +1,6 @@ """ +.. redirect-from: /tutorials/intermediate/legend_guide + .. _legend_guide: ============ @@ -13,7 +15,6 @@ :func:`~matplotlib.pyplot.legend` - please ensure you are familiar with contents of that documentation before proceeding with this guide. - This guide makes use of some common terms, which are documented here for clarity: diff --git a/galleries/users_explain/quick_start.py b/galleries/users_explain/quick_start.py index 3f658f0a8fce..e203d042f74a 100644 --- a/galleries/users_explain/quick_start.py +++ b/galleries/users_explain/quick_start.py @@ -379,7 +379,7 @@ def my_plotter(ax, data1, data2, param_dict): # %% # Legends in Matplotlib are quite flexible in layout, placement, and what # Artists they can represent. They are discussed in detail in -# :doc:`/tutorials/intermediate/legend_guide`. +# :ref:`legend_guide`. # # Axis scales and ticks # ===================== diff --git a/galleries/users_explain/text/text_intro.py b/galleries/users_explain/text/text_intro.py index efca26c1b813..eccd584ce36f 100644 --- a/galleries/users_explain/text/text_intro.py +++ b/galleries/users_explain/text/text_intro.py @@ -424,6 +424,6 @@ def formatoddticks(x, pos): # Legends and Annotations # ======================= # -# - Legends: :doc:`/tutorials/intermediate/legend_guide` +# - Legends: :ref:`legend_guide` # - Annotations: :ref:`annotations` # diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py index 5cec7d87247f..23c57105ca5e 100644 --- a/lib/matplotlib/axes/_axes.py +++ b/lib/matplotlib/axes/_axes.py @@ -303,7 +303,7 @@ def legend(self, *args, **kwargs): Notes ----- Some artists are not supported by this function. See - :doc:`/tutorials/intermediate/legend_guide` for details. + :ref:`legend_guide` for details. Examples -------- diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index ca85346306d0..9d3f630ea1ac 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1108,7 +1108,7 @@ def legend(self, *args, **kwargs): Notes ----- Some artists are not supported by this function. See - :doc:`/tutorials/intermediate/legend_guide` for details. + :ref:`legend_guide` for details. """ handles, labels, extra_args, kwargs = mlegend._parse_legend_args( diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py index 11fb0c3ba4a5..95b0e50b3015 100644 --- a/lib/matplotlib/legend.py +++ b/lib/matplotlib/legend.py @@ -6,8 +6,8 @@ It is unlikely that you would ever create a Legend instance manually. Most users would normally create a legend via the `~.Axes.legend` - function. For more details on legends there is also a :doc:`legend guide - `. + function. For more details on legends there is also a :ref:`legend guide + `. The `Legend` class is a container of legend handles and legend texts. @@ -17,7 +17,7 @@ types are covered by the default legend handlers, custom legend handlers can be defined to support arbitrary objects. -See the :doc:`legend guide ` for more +See the :ref`` for more information. """ @@ -314,7 +314,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas): right side of the layout. In addition to the values of *loc* listed above, we have 'outside right upper', 'outside right lower', 'outside left upper', and 'outside left lower'. See - :doc:`/tutorials/intermediate/legend_guide` for more details. + :ref:`legend_guide` for more details. """ _legend_kw_figure_st = ( @@ -863,7 +863,7 @@ def _init_legend_box(self, handles, labels, markerfirst=True): f"{type(orig_handle).__name__} " "instances.\nA proxy artist may be used " "instead.\nSee: https://matplotlib.org/" - "stable/tutorials/intermediate/legend_guide.html" + "stable/users/explain/axes/legend_guide.html" "#controlling-the-legend-entries") # No handle for this artist, so we just defer to None. handle_list.append(None) diff --git a/lib/matplotlib/legend_handler.py b/lib/matplotlib/legend_handler.py index 0790150e3a9c..ed902193c5f6 100644 --- a/lib/matplotlib/legend_handler.py +++ b/lib/matplotlib/legend_handler.py @@ -5,8 +5,8 @@ This is a low-level legend API, which most end users do not need. - We recommend that you are familiar with the :doc:`legend guide - ` before reading this documentation. + We recommend that you are familiar with the :ref:`legend guide + ` before reading this documentation. Legend handlers are expected to be a callable object with a following signature:: diff --git a/pyproject.toml b/pyproject.toml index 1ac08336f053..71f1640434d8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -119,7 +119,7 @@ convention = "numpy" "galleries/users_explain/colors/colors.py" = ["E402"] "galleries/tutorials/intermediate/artists.py" = ["E402"] "galleries/users_explain/figure/constrainedlayout_guide.py" = ["E402"] -"galleries/tutorials/intermediate/legend_guide.py" = ["E402"] +"galleries/users_explain/axes/legend_guide.py" = ["E402"] "galleries/users_explain/figure/tight_layout_guide.py" = ["E402"] "galleries/users_explain/animation_tutorial.py" = ["E501"] "galleries/tutorials/introductory/images.py" = ["E501"] From 2b606921fa0edbf638bf63f1207791522499ff36 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Sun, 5 Mar 2023 20:46:30 -0800 Subject: [PATCH 17/23] DOC: moved color_cycle tutorial --- doc/users/prev_whats_new/whats_new_1.5.rst | 4 ++-- .../examples/lines_bars_and_markers/line_demo_dash_control.py | 2 +- galleries/examples/lines_bars_and_markers/linestyles.py | 2 +- .../intermediate => users_explain/artists}/color_cycle.py | 4 ++++ galleries/users_explain/artists/index.rst | 1 + galleries/users_explain/colors/colors.py | 2 +- lib/matplotlib/mpl-data/matplotlibrc | 2 +- 7 files changed, 11 insertions(+), 6 deletions(-) rename galleries/{tutorials/intermediate => users_explain/artists}/color_cycle.py (98%) diff --git a/doc/users/prev_whats_new/whats_new_1.5.rst b/doc/users/prev_whats_new/whats_new_1.5.rst index b94355b97b93..0dd142d989f0 100644 --- a/doc/users/prev_whats_new/whats_new_1.5.rst +++ b/doc/users/prev_whats_new/whats_new_1.5.rst @@ -104,8 +104,8 @@ defining property cycles. Adding cyclers together will be like you are You can even multiply cyclers, which is like using `itertools.product` on two or more property cycles. -.. figure:: ../../tutorials/intermediate/images/sphx_glr_color_cycle_001.png - :target: ../../tutorials/intermediate/color_cycle.html +.. figure:: /users/explain/artists/images/sphx_glr_color_cycle_001.png + :target: /users/explain/artists/color_cycle.html :align: center :scale: 50 diff --git a/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py b/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py index abd8d6750e70..c695bc51c176 100644 --- a/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py +++ b/galleries/examples/lines_bars_and_markers/line_demo_dash_control.py @@ -14,7 +14,7 @@ line. *Note*: The dash style can also be configured via a -:doc:`property_cycle ` +:ref:`property_cycle ` by passing a list of dash sequences using the keyword *dashes* to the cycler. This is not shown within this example. diff --git a/galleries/examples/lines_bars_and_markers/linestyles.py b/galleries/examples/lines_bars_and_markers/linestyles.py index cf4bfa0eb3a6..f3ce3aa6e7ec 100644 --- a/galleries/examples/lines_bars_and_markers/linestyles.py +++ b/galleries/examples/lines_bars_and_markers/linestyles.py @@ -13,7 +13,7 @@ *Note*: The dash style can also be configured via `.Line2D.set_dashes` as shown in :doc:`/gallery/lines_bars_and_markers/line_demo_dash_control` and passing a list of dash sequences using the keyword *dashes* to the -cycler in :doc:`property_cycle `. +cycler in :ref:`property_cycle `. """ import matplotlib.pyplot as plt import numpy as np diff --git a/galleries/tutorials/intermediate/color_cycle.py b/galleries/users_explain/artists/color_cycle.py similarity index 98% rename from galleries/tutorials/intermediate/color_cycle.py rename to galleries/users_explain/artists/color_cycle.py index e1dc898f6d4c..715b75a88ff4 100644 --- a/galleries/tutorials/intermediate/color_cycle.py +++ b/galleries/users_explain/artists/color_cycle.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/color_cycle + +.. _color_cycle: + =================== Styling with cycler =================== diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index 8e71deff8f22..4bc9187c8fa8 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -192,6 +192,7 @@ More details .. toctree:: :maxdepth: 1 + Concept: Automated color cycle Concept: optimizing Artists for performance In Depth: understanding the extent keyword argument of imshow transforms_tutorial \ No newline at end of file diff --git a/galleries/users_explain/colors/colors.py b/galleries/users_explain/colors/colors.py index 29cedaaa3ef3..bd8cdb299a85 100644 --- a/galleries/users_explain/colors/colors.py +++ b/galleries/users_explain/colors/colors.py @@ -131,7 +131,7 @@ # ==================== # # Matplotlib converts "CN" colors to RGBA when drawing Artists. The -# :doc:`/tutorials/intermediate/color_cycle` section contains additional +# :ref:`color_cycle` section contains additional # information about controlling colors and style properties. diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc index b2901d0bde11..1cddb67de8cb 100644 --- a/lib/matplotlib/mpl-data/matplotlibrc +++ b/lib/matplotlib/mpl-data/matplotlibrc @@ -416,7 +416,7 @@ # As opposed to all other parameters in this file, the color # values must be enclosed in quotes for this parameter, # e.g. '1f77b4', instead of 1f77b4. - # See also https://matplotlib.org/stable/tutorials/intermediate/color_cycle.html + # See also https://matplotlib.org/stable/users/explain/artists/color_cycle.html # for more details on prop_cycle usage. #axes.xmargin: .05 # x margin. See `axes.Axes.margins` #axes.ymargin: .05 # y margin. See `axes.Axes.margins` From 645d4b95b0287de8054323992d379016080ed1ad Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Mon, 6 Mar 2023 14:08:45 -0800 Subject: [PATCH 18/23] DOC: fix flake8 [ci doc] --- .flake8 | 8 +++--- galleries/users_explain/animations/README.txt | 9 ++++++ .../{ => animations}/animations.py | 0 .../animations}/blitting.py | 4 +++ galleries/users_explain/artists/index.rst | 2 +- galleries/users_explain/index.rst | 2 +- galleries/users_explain/text/fonts.py | 13 +++++---- lib/matplotlib/artist.py | 2 +- lib/matplotlib/widgets.py | 28 ++++++++++++------- pyproject.toml | 6 ++-- 10 files changed, 49 insertions(+), 25 deletions(-) create mode 100644 galleries/users_explain/animations/README.txt rename galleries/users_explain/{ => animations}/animations.py (100%) rename galleries/{tutorials/advanced => users_explain/animations}/blitting.py (99%) diff --git a/.flake8 b/.flake8 index 311d1508fa1d..62f11e1d5f31 100644 --- a/.flake8 +++ b/.flake8 @@ -58,13 +58,13 @@ per-file-ignores = galleries/tutorials/advanced/path_tutorial.py: E402 galleries/tutorials/advanced/patheffects_guide.py: E402 galleries/users_explain/artists/transforms_tutorial.py: E402, E501 - galleries/users_explain/colormaps.py: E501 + galleries/users_explain/colors/colormaps.py: E501 galleries/users_explain/colors/colors.py: E402 galleries/tutorials/intermediate/artists.py: E402 - galleries/users_explain/figure/constrainedlayout_guide.py: E402 + galleries/users_explain/axes/constrainedlayout_guide.py: E402 galleries/users_explain/axes/legend_guide.py: E402 - galleries/users_explain/figure/tight_layout_guide.py: E402 - galleries/users_explain/animation_tutorial.py: E501 + galleries/users_explain/axes/tight_layout_guide.py: E402 + galleries/users_explain/animations/animations.py: E501 galleries/tutorials/introductory/images.py: E501 galleries/tutorials/introductory/pyplot.py: E402, E501 galleries/users_explain/text/annotations.py: E402, E501 diff --git a/galleries/users_explain/animations/README.txt b/galleries/users_explain/animations/README.txt new file mode 100644 index 000000000000..a7d37a0242e6 --- /dev/null +++ b/galleries/users_explain/animations/README.txt @@ -0,0 +1,9 @@ +=========================== +Animations using Matplotlib +=========================== + +Based on its plotting functionality, Matplotlib also provides an interface to +generate animations using the `~matplotlib.animation` module. An +animation is a sequence of frames where each frame corresponds to a plot on a +`~matplotlib.figure.Figure`. This tutorial covers a general guideline on +how to create such animations and the different options available. diff --git a/galleries/users_explain/animations.py b/galleries/users_explain/animations/animations.py similarity index 100% rename from galleries/users_explain/animations.py rename to galleries/users_explain/animations/animations.py diff --git a/galleries/tutorials/advanced/blitting.py b/galleries/users_explain/animations/blitting.py similarity index 99% rename from galleries/tutorials/advanced/blitting.py rename to galleries/users_explain/animations/blitting.py index 52d0f5984c78..a68f6af31963 100644 --- a/galleries/tutorials/advanced/blitting.py +++ b/galleries/users_explain/animations/blitting.py @@ -1,4 +1,8 @@ """ +.. redirected-from: /tutorials/advanced/blitting + +.. _blitting: + ================================== Faster rendering by using blitting ================================== diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index 4bc9187c8fa8..a4a8d708a1bf 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -195,4 +195,4 @@ More details Concept: Automated color cycle Concept: optimizing Artists for performance In Depth: understanding the extent keyword argument of imshow - transforms_tutorial \ No newline at end of file + transforms_tutorial diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index f466b4ca0ddf..28456d393777 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -16,4 +16,4 @@ Using Matplotlib axis/index colors/index text/index - animations + animations/index diff --git a/galleries/users_explain/text/fonts.py b/galleries/users_explain/text/fonts.py index d703c85f989d..dd27f4f573d1 100644 --- a/galleries/users_explain/text/fonts.py +++ b/galleries/users_explain/text/fonts.py @@ -45,7 +45,8 @@ - Hinting supported (virtual machine processes the "hints") * - Non-subsetted through Matplotlib - Subsetted via external module ttconv - - Subsetted via external module `fontTools `__ + - Subsetted via external module + `fontTools `__ .. note:: @@ -58,9 +59,11 @@ - Type 42 fonts (PS): - PostScript wrapper around TrueType fonts - - 42 is the `Answer to Life, the Universe, and Everything! `_ - - Matplotlib uses the external library `fontTools `__ - to subset these types of fonts + - 42 is the `Answer to Life, the Universe, and Everything! + `_ + - Matplotlib uses the external library + `fontTools `__ to subset these types of + fonts - OpenType fonts: @@ -195,4 +198,4 @@ A majority of this work was done by Aitik Gupta supported by Google Summer of Code 2021. -""" \ No newline at end of file +""" diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index f8eeb2e224ab..7101d477c145 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -1067,7 +1067,7 @@ def set_animated(self, b): using blitting. See also `matplotlib.animation` and - :doc:`/tutorials/advanced/blitting`. + :ref:`blitting`. Parameters ---------- diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index 38c6b1c01009..c8209d1616a4 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -187,7 +187,7 @@ def __init__(self, ax, label, image=None, The color of the button when the mouse is over it. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. .. versionadded:: 3.7 """ @@ -1030,9 +1030,13 @@ def __init__(self, ax, labels, actives=None, *, useblit=True, same length as *labels*. If not given, all buttons are unchecked. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. +<<<<<<< HEAD See the tutorial :doc:`/tutorials/advanced/blitting` for details. .. versionadded:: 3.7 +======= + See the tutorial :ref:`blitting` for details. +>>>>>>> b6f353389a (DOC: fix flake8 [ci doc]) label_props : dict, optional Dictionary of `.Text` properties to be used for the labels. @@ -1637,9 +1641,13 @@ def __init__(self, ax, labels, active=0, activecolor=None, *, specified here or in *radio_props*. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. +<<<<<<< HEAD See the tutorial :doc:`/tutorials/advanced/blitting` for details. .. versionadded:: 3.7 +======= + See the tutorial :ref:`blitting` for details. +>>>>>>> b6f353389a (DOC: fix flake8 [ci doc]) label_props : dict or list of dict, optional Dictionary of `.Text` properties to be used for the labels. @@ -1958,7 +1966,7 @@ class Cursor(AxesWidget): Whether to draw the vertical line. useblit : bool, default: False Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. Other Parameters ---------------- @@ -2052,7 +2060,7 @@ class MultiCursor(Widget): useblit : bool, default: True Use blitting for faster drawing if supported by the backend. - See the tutorial :doc:`/tutorials/advanced/blitting` + See the tutorial :ref:`blitting` for details. horizOn : bool, default: False @@ -2567,7 +2575,7 @@ def on_select(min: float, max: float) -> Any useblit : bool, default: False If True, use the backend-dependent blitting features for faster - canvas updates. See the tutorial :doc:`/tutorials/advanced/blitting` + canvas updates. See the tutorial :ref:`blitting` for details. props : dict, optional @@ -2984,7 +2992,7 @@ class ToolLineHandles: Additional line properties. See `matplotlib.lines.Line2D`. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ @@ -3095,7 +3103,7 @@ class ToolHandles: Additional marker properties. See `matplotlib.lines.Line2D`. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ @@ -3172,7 +3180,7 @@ def onselect(eclick: MouseEvent, erelease: MouseEvent) useblit : bool, default: False Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional @@ -3798,7 +3806,7 @@ def onselect(verts): passed the vertices of the selected path. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional Properties with which the line is drawn, see `matplotlib.lines.Line2D` @@ -3874,7 +3882,7 @@ class PolygonSelector(_SelectorWidget): useblit : bool, default: False Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. props : dict, optional @@ -4223,7 +4231,7 @@ class Lasso(AxesWidget): passed the vertices of the selected path. useblit : bool, default: True Whether to use blitting for faster drawing (if supported by the - backend). See the tutorial :doc:`/tutorials/advanced/blitting` + backend). See the tutorial :ref:`blitting` for details. """ diff --git a/pyproject.toml b/pyproject.toml index 71f1640434d8..2697aa92a74d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -118,10 +118,10 @@ convention = "numpy" "galleries/users_explain/colors/colormaps.py" = ["E501"] "galleries/users_explain/colors/colors.py" = ["E402"] "galleries/tutorials/intermediate/artists.py" = ["E402"] -"galleries/users_explain/figure/constrainedlayout_guide.py" = ["E402"] +"galleries/users_explain/axes/constrainedlayout_guide.py" = ["E402"] "galleries/users_explain/axes/legend_guide.py" = ["E402"] -"galleries/users_explain/figure/tight_layout_guide.py" = ["E402"] -"galleries/users_explain/animation_tutorial.py" = ["E501"] +"galleries/users_explain/axes/tight_layout_guide.py" = ["E402"] +"galleries/users_explain/animations/animation.py" = ["E501"] "galleries/tutorials/introductory/images.py" = ["E501"] "galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] "galleries/users_explain/text/annotations.py" = ["E402", "E501"] From f24d06788530a5636c6697adf720a1641cf16989 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Mon, 6 Mar 2023 17:28:12 -0800 Subject: [PATCH 19/23] FIX --- doc/users/prev_whats_new/whats_new_3.7.0.rst | 2 +- galleries/examples/event_handling/README.txt | 2 +- .../subplots_axes_and_figures/auto_subplots_adjust.py | 2 +- galleries/users_explain/animations/blitting.py | 2 +- galleries/users_explain/artists/index.rst | 2 +- galleries/users_explain/artists/transforms_tutorial.py | 2 +- galleries/users_explain/axes/index.rst | 4 ++-- galleries/users_explain/axes/legend_guide.py | 2 +- galleries/users_explain/figure/event_handling.rst | 3 ++- galleries/users_explain/figure/interactive.rst | 2 +- galleries/users_explain/figure/interactive_guide.rst | 4 ++-- 11 files changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/users/prev_whats_new/whats_new_3.7.0.rst b/doc/users/prev_whats_new/whats_new_3.7.0.rst index 5595e142a337..1834cbf3726f 100644 --- a/doc/users/prev_whats_new/whats_new_3.7.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.7.0.rst @@ -445,7 +445,7 @@ functions can e.g. attach callbacks or modify the toolbar. See New & Improved Narrative Documentation ====================================== -* Brand new :doc:`Animations ` tutorial. +* Brand new :ref:`Animations ` tutorial. * New grouped and stacked `bar chart <../../gallery/index.html#lines_bars_and_markers>`_ examples. * New section for new contributors and reorganized git instructions in the :ref:`contributing guide`. * Restructured :ref:`annotations` tutorial. diff --git a/galleries/examples/event_handling/README.txt b/galleries/examples/event_handling/README.txt index 46aed29b56bc..44aa9cf3ac6a 100644 --- a/galleries/examples/event_handling/README.txt +++ b/galleries/examples/event_handling/README.txt @@ -3,7 +3,7 @@ Event handling ============== -Matplotlib supports :doc:`event handling` with +Matplotlib supports :ref:`event handling ` with a GUI neutral event model, so you can connect to Matplotlib events without knowledge of what user interface Matplotlib will ultimately be plugged in to. This has two advantages: the code you write will be more portable, and diff --git a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py index 099ddc6e546a..3bd0d3f2bec1 100644 --- a/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py +++ b/galleries/examples/subplots_axes_and_figures/auto_subplots_adjust.py @@ -19,7 +19,7 @@ set the subplot parameters accordingly. Its main purpose is to illustrate some advanced concepts like reading out text positions, working with bounding boxes and transforms and using -:ref:`events `. But it can also serve as a starting +:ref:`events `. But it can also serve as a starting point if you want to automate the layouting and need more flexibility than tight layout and constrained layout. diff --git a/galleries/users_explain/animations/blitting.py b/galleries/users_explain/animations/blitting.py index a68f6af31963..b6e658f8a3cb 100644 --- a/galleries/users_explain/animations/blitting.py +++ b/galleries/users_explain/animations/blitting.py @@ -1,5 +1,5 @@ """ -.. redirected-from: /tutorials/advanced/blitting +.. redirect-from:: /tutorials/advanced/blitting .. _blitting: diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index a4a8d708a1bf..f6e9c641df64 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -138,7 +138,7 @@ Changing Artist data In addition to styling properties like *color* and *linewidth*, the Line2D object has a *data* property. You can set the data after the line has been created using `.Line2D.set_data`. This is often used for Animations, where the -same line is shown evolving over time (see :doc:`../animations`) +same line is shown evolving over time (see :doc:`../animations/index`) .. plot:: :include-source: diff --git a/galleries/users_explain/artists/transforms_tutorial.py b/galleries/users_explain/artists/transforms_tutorial.py index 0c544c8f5e20..c6e71ad111d7 100644 --- a/galleries/users_explain/artists/transforms_tutorial.py +++ b/galleries/users_explain/artists/transforms_tutorial.py @@ -213,7 +213,7 @@ # This is one good reason why you rarely want to work in *display* # space, but you can connect to the ``'on_draw'`` # :class:`~matplotlib.backend_bases.Event` to update *figure* -# coordinates on figure draws; see :ref:`event-handling-tutorial`. +# coordinates on figure draws; see :ref:`event-handling`. # # When you change the x or y limits of your axes, the data limits are # updated so the transformation yields a new display point. Note that diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 54583212cb40..8df2a3c3c599 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -5,7 +5,7 @@ Axes (or Subplots) Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods that can be used to -add data to the Axes. An Axes typically has a pair of :ref:`Axis <../axis/>` +add data to the Axes. An Axes typically has a pair of :doc:`Axis <../axis/index>` Artists that define the data co-ordinate system, and include methods to add annotations like x- and y-labels, titles, and legends. @@ -130,7 +130,7 @@ Note that text can also be added to axes using `~.axes.Axes.text`, and `~.axes.A Axes limits, scales, and ticking -------------------------------- -Each Axes has two (or more) `~.axis.Axis` objects, that can be accessed via :attr:`~matplotlib.axes.Axes.xaxis` and :attr:`~matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. +Each Axes has two (or more) `~.axis.Axis` objects, that can be accessed via :attr:`~matplotlib.axes.Axes.xaxis` and :attr:`~matplotlib.axes.Axes.yaxis` properties. These have substantial number of methods on them, and for highly customizable Axis-es it is useful to read more about that API (:doc:`../axis/index`). However, the Axes class offers a number of helpers for the most common of these methods. Indeed, the `~.axes.Axes.set_xlabel`, discussed above, is a helper for the `~.Axis.set_label_text`. Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.axes.Axes.set_ylim`), or more fundamentally the scale of the axes. So for instance, we can make an Axis have a logarithmic scale, and zoom in on a sub-portion of the data: diff --git a/galleries/users_explain/axes/legend_guide.py b/galleries/users_explain/axes/legend_guide.py index 48304e4a217c..9900b0aa4bdd 100644 --- a/galleries/users_explain/axes/legend_guide.py +++ b/galleries/users_explain/axes/legend_guide.py @@ -1,5 +1,5 @@ """ -.. redirect-from: /tutorials/intermediate/legend_guide +.. redirect-from:: /tutorials/intermediate/legend_guide .. _legend_guide: diff --git a/galleries/users_explain/figure/event_handling.rst b/galleries/users_explain/figure/event_handling.rst index c7fe7f5ea38d..f72b9d96262f 100644 --- a/galleries/users_explain/figure/event_handling.rst +++ b/galleries/users_explain/figure/event_handling.rst @@ -1,6 +1,7 @@ .. redirect-from:: /users/event_handling -.. _event-handling-tutorial: +.. _event-handling: +.. _event_handling: ************************** Event handling and picking diff --git a/galleries/users_explain/figure/interactive.rst b/galleries/users_explain/figure/interactive.rst index 3b64398e2b3e..5422fa47bfd2 100644 --- a/galleries/users_explain/figure/interactive.rst +++ b/galleries/users_explain/figure/interactive.rst @@ -53,7 +53,7 @@ collected. `.Figure`\s can be closed and deregistered from `.pyplot` individuall For more discussion of Matplotlib's event system and integrated event loops: - :ref:`interactive_figures_and_eventloops` - - :ref:`event-handling-tutorial` + - :ref:`event-handling` .. _ipython-pylab: diff --git a/galleries/users_explain/figure/interactive_guide.rst b/galleries/users_explain/figure/interactive_guide.rst index 9c110967d94a..39f5402708b7 100644 --- a/galleries/users_explain/figure/interactive_guide.rst +++ b/galleries/users_explain/figure/interactive_guide.rst @@ -18,7 +18,7 @@ you can use to build sophisticated interactive graphs. This guide is meant to be an introduction to the low-level details of how Matplotlib integration with a GUI event loop works. For a more practical introduction to the Matplotlib event API see :ref:`event -handling system `, `Interactive Tutorial +handling system `, `Interactive Tutorial `__, and `Interactive Applications using Matplotlib `__. @@ -64,7 +64,7 @@ capturing user interactions and passing them back to the application details depend on the toolkit. Matplotlib has a :ref:`backend ` for each GUI toolkit we support which uses the toolkit API to bridge the toolkit UI events into Matplotlib's :ref:`event -handling system `. You can then use +handling system `. You can then use `.FigureCanvasBase.mpl_connect` to connect your function to Matplotlib's event handling system. This allows you to directly interact with your data and write GUI toolkit agnostic user From 74b67f2e47fc0c6a4c5fd8362a9b29d09671529f Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Mon, 6 Mar 2023 19:56:28 -0800 Subject: [PATCH 20/23] Moved path and patheffects to artist [ci doc] --- .flake8 | 4 ++-- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/prev_whats_new/whats_new_1.4.rst | 2 +- galleries/examples/misc/tickedstroke_demo.py | 2 +- galleries/users_explain/artists/index.rst | 2 ++ .../advanced => users_explain/artists}/patheffects_guide.py | 4 ++++ .../path_tutorial.py => users_explain/artists/paths.py} | 4 ++++ galleries/users_explain/axes/index.rst | 2 +- galleries/users_explain/axis/index.rst | 1 - galleries/users_explain/figure/backends.rst | 2 +- galleries/users_explain/figure/index.rst | 1 - lib/matplotlib/patheffects.py | 2 +- pyproject.toml | 4 ++-- 13 files changed, 20 insertions(+), 12 deletions(-) rename galleries/{tutorials/advanced => users_explain/artists}/patheffects_guide.py (98%) rename galleries/{tutorials/advanced/path_tutorial.py => users_explain/artists/paths.py} (99%) diff --git a/.flake8 b/.flake8 index 62f11e1d5f31..ad41be9409d7 100644 --- a/.flake8 +++ b/.flake8 @@ -55,8 +55,8 @@ per-file-ignores = lib/pylab.py: F401, F403 doc/conf.py: E402 - galleries/tutorials/advanced/path_tutorial.py: E402 - galleries/tutorials/advanced/patheffects_guide.py: E402 + galleries/users_explain/artists/paths.py: E402 + galleries/users_explain/artists/patheffects_guide.py: E402 galleries/users_explain/artists/transforms_tutorial.py: E402, E501 galleries/users_explain/colors/colormaps.py: E501 galleries/users_explain/colors/colors.py: E402 diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index 0abf98ed8f8c..af59468b1331 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -14,7 +14,7 @@ New documentation Jae-Joon Lee has written two new guides :ref:`legend_guide` and :ref:`plotting-guide-annotation`. Michael Sarahan has written :doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on -working with paths and transformations: :doc:`/tutorials/advanced/path_tutorial` and +working with paths and transformations: :ref:`paths` and :ref:`transforms_tutorial`. .. _whats-new-mplot3d: diff --git a/doc/users/prev_whats_new/whats_new_1.4.rst b/doc/users/prev_whats_new/whats_new_1.4.rst index b3ecf939b589..b8a85638646b 100644 --- a/doc/users/prev_whats_new/whats_new_1.4.rst +++ b/doc/users/prev_whats_new/whats_new_1.4.rst @@ -406,7 +406,7 @@ instead of ``:context:`` any time you want to reset the context. Legend and PathEffects documentation ------------------------------------ -The :ref:`legend_guide` and :doc:`/tutorials/advanced/patheffects_guide` have both been +The :ref:`legend_guide` and :ref:`patheffects_guide` have both been updated to better reflect the full potential of each of these powerful features. diff --git a/galleries/examples/misc/tickedstroke_demo.py b/galleries/examples/misc/tickedstroke_demo.py index 9dbe77025d92..451d7fa6fe1a 100644 --- a/galleries/examples/misc/tickedstroke_demo.py +++ b/galleries/examples/misc/tickedstroke_demo.py @@ -6,7 +6,7 @@ Matplotlib's :mod:`.patheffects` can be used to alter the way paths are drawn at a low enough level that they can affect almost anything. -The :doc:`patheffects guide` +The :ref:`patheffects guide` details the use of patheffects. The `~matplotlib.patheffects.TickedStroke` patheffect illustrated here diff --git a/galleries/users_explain/artists/index.rst b/galleries/users_explain/artists/index.rst index f6e9c641df64..1b5e248d1ea7 100644 --- a/galleries/users_explain/artists/index.rst +++ b/galleries/users_explain/artists/index.rst @@ -194,5 +194,7 @@ More details Concept: Automated color cycle Concept: optimizing Artists for performance + Concept: Paths + Concept: Path effects guide In Depth: understanding the extent keyword argument of imshow transforms_tutorial diff --git a/galleries/tutorials/advanced/patheffects_guide.py b/galleries/users_explain/artists/patheffects_guide.py similarity index 98% rename from galleries/tutorials/advanced/patheffects_guide.py rename to galleries/users_explain/artists/patheffects_guide.py index ec396f6842ef..259261fb09d4 100644 --- a/galleries/tutorials/advanced/patheffects_guide.py +++ b/galleries/users_explain/artists/patheffects_guide.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advance/patheffects_guide + +.. _patheffects_guide: + ================== Path effects guide ================== diff --git a/galleries/tutorials/advanced/path_tutorial.py b/galleries/users_explain/artists/paths.py similarity index 99% rename from galleries/tutorials/advanced/path_tutorial.py rename to galleries/users_explain/artists/paths.py index 82b663be61b6..d505711fd1c0 100644 --- a/galleries/tutorials/advanced/path_tutorial.py +++ b/galleries/users_explain/artists/paths.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/advanced/path_tutorial + +.. _paths: + ============= Path Tutorial ============= diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 8df2a3c3c599..57f893e0e18f 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -6,7 +6,7 @@ Axes (or Subplots) Matplotlib `~.axes.Axes` are the gateway to creating your data visualizations. Once an Axes is placed on a figure there are many methods that can be used to add data to the Axes. An Axes typically has a pair of :doc:`Axis <../axis/index>` -Artists that define the data co-ordinate system, and include methods to add +Artists that define the data coordinate system, and include methods to add annotations like x- and y-labels, titles, and legends. .. _anatomy_local: diff --git a/galleries/users_explain/axis/index.rst b/galleries/users_explain/axis/index.rst index 22339261502c..e6b8b81c8018 100644 --- a/galleries/users_explain/axis/index.rst +++ b/galleries/users_explain/axis/index.rst @@ -4,4 +4,3 @@ Controlling and labelling Axis objects -------------------------------------- Some good material in artist tutorial that should be cribbed from or used here. - diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst index c810c3ce30e6..97e1239b8cfe 100644 --- a/galleries/users_explain/figure/backends.rst +++ b/galleries/users_explain/figure/backends.rst @@ -240,4 +240,4 @@ methods above. If ``name.of.the.backend`` is the module containing the 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`. \ No newline at end of file +Information for backend implementers is available at :ref:`writing_backend_interface`. diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index a3420f47aabb..991bd9032e39 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -268,4 +268,3 @@ More reading In depth: Interactive figures and asynchronous programming In depth: Event handling In depth: Writing a backend -- the pyplot interface - diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py index 3325fe03d805..ed19db2ad27b 100644 --- a/lib/matplotlib/patheffects.py +++ b/lib/matplotlib/patheffects.py @@ -3,7 +3,7 @@ `.Line2D` and `.Patch`. .. seealso:: - :doc:`/tutorials/advanced/patheffects_guide` + :ref:`patheffects_guide` """ from matplotlib.backend_bases import RendererBase diff --git a/pyproject.toml b/pyproject.toml index 2697aa92a74d..cff0fe04818a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -112,8 +112,8 @@ convention = "numpy" "lib/mpl_toolkits/axisartist/__init__.py" = ["F401"] "lib/pylab.py" = ["F401", "F403"] -"galleries/tutorials/advanced/path_tutorial.py" = ["E402"] -"galleries/tutorials/advanced/patheffects_guide.py" = ["E402"] +"galleries/users_explain/artists/paths.py" = ["E402"] +"galleries/users_explain/artists/patheffects_guide.py" = ["E402"] "galleries/users_explain/artists/transforms_tutorial.py" = ["E402", "E501"] "galleries/users_explain/colors/colormaps.py" = ["E501"] "galleries/users_explain/colors/colors.py" = ["E402"] From 0b687e1c754e7a7b3beb39e9432b22fca0ab15cb Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Tue, 7 Mar 2023 13:46:44 -0800 Subject: [PATCH 21/23] DOC: toolkits [ci doc] --- doc/api/toolkits/mplot3d.rst | 2 +- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/prev_whats_new/whats_new_1.1.rst | 2 +- .../axes_grid1/simple_axes_divider1.py | 2 +- .../axes_grid1/simple_axes_divider3.py | 2 +- galleries/users_explain/index.rst | 1 + .../toolkits/README.txt | 2 + .../toolkits/axes_grid.py | 63 ++++++++++--------- .../toolkits/axisartist.py | 61 +++++++++--------- .../toolkits/mplot3d.py | 57 +++++++++-------- 10 files changed, 105 insertions(+), 89 deletions(-) rename galleries/{tutorials => users_explain}/toolkits/README.txt (80%) rename galleries/{tutorials => users_explain}/toolkits/axes_grid.py (84%) rename galleries/{tutorials => users_explain}/toolkits/axisartist.py (90%) rename galleries/{tutorials => users_explain}/toolkits/mplot3d.py (60%) diff --git a/doc/api/toolkits/mplot3d.rst b/doc/api/toolkits/mplot3d.rst index fc6c4cbad6d1..f14918314b97 100644 --- a/doc/api/toolkits/mplot3d.rst +++ b/doc/api/toolkits/mplot3d.rst @@ -12,7 +12,7 @@ and feel as regular 2D plots. Not the fastest or most feature complete 3D library out there, but it ships with Matplotlib and thus may be a lighter weight solution for some use cases. -See the :doc:`mplot3d tutorial ` for +See the :ref:`mplot3d tutorial ` for more information. .. image:: /_static/demo_mplot3d.png diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index af59468b1331..0865320316e5 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -26,7 +26,7 @@ Reinier Heeres has ported John Porter's mplot3d over to the new matplotlib transformations framework, and it is now available as a toolkit mpl_toolkits.mplot3d (which now comes standard with all mpl installs). See :ref:`mplot3d-examples-index` and -:doc:`/tutorials/toolkits/mplot3d`. +:ref:`mplot3d`. .. plot:: diff --git a/doc/users/prev_whats_new/whats_new_1.1.rst b/doc/users/prev_whats_new/whats_new_1.1.rst index 59a53ca3c801..cad5cc33c773 100644 --- a/doc/users/prev_whats_new/whats_new_1.1.rst +++ b/doc/users/prev_whats_new/whats_new_1.1.rst @@ -133,7 +133,7 @@ as 2D plotting, Ben Root has made several improvements to the improved to bring the class towards feature-parity with regular Axes objects -* Documentation for :doc:`/tutorials/toolkits/mplot3d` was significantly expanded +* Documentation for :ref:`mplot3d` was significantly expanded * Axis labels and orientation improved diff --git a/galleries/examples/axes_grid1/simple_axes_divider1.py b/galleries/examples/axes_grid1/simple_axes_divider1.py index 0a35ebc92e6e..4b7edc27ae9b 100644 --- a/galleries/examples/axes_grid1/simple_axes_divider1.py +++ b/galleries/examples/axes_grid1/simple_axes_divider1.py @@ -3,7 +3,7 @@ Simple Axes Divider 1 ===================== -See also :doc:`/tutorials/toolkits/axes_grid`. +See also :ref:`axes_grid`. """ import matplotlib.pyplot as plt diff --git a/galleries/examples/axes_grid1/simple_axes_divider3.py b/galleries/examples/axes_grid1/simple_axes_divider3.py index e9573f3c5c2a..54050633d4ea 100644 --- a/galleries/examples/axes_grid1/simple_axes_divider3.py +++ b/galleries/examples/axes_grid1/simple_axes_divider3.py @@ -3,7 +3,7 @@ Simple axes divider 3 ===================== -See also :doc:`/tutorials/toolkits/axes_grid`. +See also :ref:`axes_grid`. """ import matplotlib.pyplot as plt diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 28456d393777..0fa5c8a15f07 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -17,3 +17,4 @@ Using Matplotlib colors/index text/index animations/index + toolkits/index diff --git a/galleries/tutorials/toolkits/README.txt b/galleries/users_explain/toolkits/README.txt similarity index 80% rename from galleries/tutorials/toolkits/README.txt rename to galleries/users_explain/toolkits/README.txt index 4a0c6ab3af64..a72d8f87a43c 100644 --- a/galleries/tutorials/toolkits/README.txt +++ b/galleries/users_explain/toolkits/README.txt @@ -1,5 +1,7 @@ .. _tutorials-toolkits: +.. redirect-from:: /tutorials/toolkits + Toolkits -------- diff --git a/galleries/tutorials/toolkits/axes_grid.py b/galleries/users_explain/toolkits/axes_grid.py similarity index 84% rename from galleries/tutorials/toolkits/axes_grid.py rename to galleries/users_explain/toolkits/axes_grid.py index 0206b7ed816b..84d1ecc4d288 100644 --- a/galleries/tutorials/toolkits/axes_grid.py +++ b/galleries/users_explain/toolkits/axes_grid.py @@ -1,5 +1,8 @@ r""" +.. redirect-from:: /tutorials/toolkits/axes_grid + .. _axes_grid1_users-guide-index: +.. _axes_grid: ====================== The axes_grid1 toolkit @@ -16,8 +19,8 @@ - AnchoredArtists_ (custom artists which are placed at an anchored position, similarly to legends). -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png - :target: ../../gallery/axes_grid1/demo_axes_grid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png + :target: /gallery/axes_grid1/demo_axes_grid.html :align: center axes_grid1 @@ -32,8 +35,8 @@ `~.axes_grid1.axes_grid.ImageGrid` can be used to achieve such a padding; see its docs for detailed API information. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png - :target: ../../gallery/axes_grid1/simple_axesgrid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axesgrid_001.png + :target: /gallery/axes_grid1/simple_axesgrid.html :align: center * The position of each axes is determined at the drawing time (see @@ -48,14 +51,14 @@ the same row all have the same height. These widths and heights are scaled in proportion to the axes' view limits (xlim or ylim). - .. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png - :target: ../../gallery/axes_grid1/simple_axesgrid2.html + .. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axesgrid2_001.png + :target: /gallery/axes_grid1/simple_axesgrid2.html :align: center The examples below show what you can do with ImageGrid. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png - :target: ../../gallery/axes_grid1/demo_axes_grid.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_grid_001.png + :target: /gallery/axes_grid1/demo_axes_grid.html :align: center AxesDivider Class @@ -79,8 +82,8 @@ colorbar whose height (or width) is in sync with the main axes -------------------------------------------------------------- -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png - :target: ../../gallery/axes_grid1/simple_colorbar.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_colorbar_001.png + :target: /gallery/axes_grid1/simple_colorbar.html :align: center scatter_hist.py with AxesDivider @@ -106,8 +109,8 @@ See the full source code below. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png - :target: ../../gallery/axes_grid1/scatter_hist_locatable_axes.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_scatter_hist_locatable_axes_001.png + :target: /gallery/axes_grid1/scatter_hist_locatable_axes.html :align: center The :doc:`/gallery/axes_grid1/scatter_hist_locatable_axes` using the @@ -141,8 +144,8 @@ Example 1: twinx ~~~~~~~~~~~~~~~~ -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png - :target: ../../gallery/axes_grid1/parasite_simple.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_parasite_simple_001.png + :target: /gallery/axes_grid1/parasite_simple.html :align: center Example 2: twin @@ -158,16 +161,16 @@ labels=["0", r"$\frac{1}{2}\pi$", r"$\pi$", r"$\frac{3}{2}\pi$", r"$2\pi$"]) -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png - :target: ../../gallery/axes_grid1/simple_axisline4.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axisline4_001.png + :target: /gallery/axes_grid1/simple_axisline4.html :align: center A more sophisticated example using twin. Note that if you change the x-limit in the host axes, the x-limit of the parasite axes will change accordingly. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png - :target: ../../gallery/axes_grid1/parasite_simple2.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_parasite_simple2_001.png + :target: /gallery/axes_grid1/parasite_simple2.html :align: center AnchoredArtists @@ -179,8 +182,8 @@ coordinates. There is limited support for arbitrary transforms. For example, the ellipse in the example below will have width and height in data coordinates. -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png - :target: ../../gallery/axes_grid1/simple_anchored_artists.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_anchored_artists_001.png + :target: /gallery/axes_grid1/simple_anchored_artists.html :align: center InsetLocator @@ -214,15 +217,15 @@ creates an inset axes whose data scale is half of the parent axes. This can be useful to mark the zoomed area on the parent axes: -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png - :target: ../../gallery/axes_grid1/inset_locator_demo.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_inset_locator_demo_001.png + :target: /gallery/axes_grid1/inset_locator_demo.html :align: center `.inset_locator.mark_inset` allows marking the location of the area represented by the inset axes: -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png - :target: ../../gallery/axes_grid1/inset_locator_demo2.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_inset_locator_demo2_001.png + :target: /gallery/axes_grid1/inset_locator_demo2.html :align: center RGBAxes @@ -240,8 +243,8 @@ r, g, b = get_rgb() # r, g, b are 2D images. ax.imshow_rgb(r, g, b) -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_demo_axes_rgb_001.png - :target: ../../gallery/axes_grid1/demo_axes_rgb.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_demo_axes_rgb_001.png + :target: /gallery/axes_grid1/demo_axes_rgb.html :align: center AxesDivider @@ -318,14 +321,14 @@ See the example, -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider1_001.png - :target: ../../gallery/axes_grid1/simple_axes_divider1.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axes_divider1_001.png + :target: /gallery/axes_grid1/simple_axes_divider1.html :align: center You can also adjust the size of each axes according to its x or y data limits (AxesX and AxesY). -.. figure:: ../../gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png - :target: ../../gallery/axes_grid1/simple_axes_divider3.html +.. figure:: /gallery/axes_grid1/images/sphx_glr_simple_axes_divider3_001.png + :target: /gallery/axes_grid1/simple_axes_divider3.html :align: center """ diff --git a/galleries/tutorials/toolkits/axisartist.py b/galleries/users_explain/toolkits/axisartist.py similarity index 90% rename from galleries/tutorials/toolkits/axisartist.py rename to galleries/users_explain/toolkits/axisartist.py index d05087e9f8b2..f09d0c70894e 100644 --- a/galleries/tutorials/toolkits/axisartist.py +++ b/galleries/users_explain/toolkits/axisartist.py @@ -1,4 +1,9 @@ r""" + +.. redirect-from:: /tutorials/toolkits/axisartist + +.. _axisartist: + ====================== The axisartist toolkit ====================== @@ -15,8 +20,8 @@ artist (AxisArtist) that can handle ticks, ticklines, etc. for curved coordinate systems. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../gallery/axisartist/demo_floating_axis.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: /gallery/axisartist/demo_floating_axis.html :align: center Since it uses special artists, some Matplotlib commands that work on @@ -60,8 +65,8 @@ ax.axis["right"].set_visible(False) ax.axis["top"].set_visible(False) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisline3_001.png - :target: ../../gallery/axisartist/simple_axisline3.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axisline3_001.png + :target: /gallery/axisartist/simple_axisline3.html :align: center It is also possible to add a horizontal axis. For example, you may have an @@ -69,8 +74,8 @@ ax.axis["y=0"] = ax.new_floating_axis(nth_coord=0, value=0) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axisartist1_001.png - :target: ../../gallery/axisartist/simple_axisartist1.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axisartist1_001.png + :target: /gallery/axisartist/simple_axisartist1.html :align: center Or a fixed axis with some offset :: @@ -92,8 +97,8 @@ Here is an example that uses ParasiteAxes. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png - :target: ../../gallery/axisartist/demo_parasite_axes2.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_parasite_axes2_001.png + :target: /gallery/axisartist/demo_parasite_axes2.html :align: center Curvilinear Grid @@ -102,8 +107,8 @@ The motivation behind the AxisArtist module is to support a curvilinear grid and ticks. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../gallery/axisartist/demo_curvelinear_grid.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: /gallery/axisartist/demo_curvelinear_grid.html :align: center Floating Axes @@ -112,8 +117,8 @@ AxisArtist also supports a Floating Axes whose outer axes are defined as floating axis. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png - :target: ../../gallery/axisartist/demo_floating_axes.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axes_001.png + :target: /gallery/axisartist/demo_floating_axes.html :align: center axisartist namespace @@ -144,8 +149,8 @@ * a curvilinear grid. * a floating axis -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png - :target: ../../gallery/axisartist/demo_floating_axis.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_floating_axis_001.png + :target: /gallery/axisartist/demo_floating_axis.html :align: center *mpl_toolkits.axisartist.Axes* class defines a *axis* attribute, which @@ -305,8 +310,8 @@ ax1.axis["left"].major_ticklabels.set_axis_direction("top") ax1.axis["right"].label.set_axis_direction("left") -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction01_001.png - :target: ../../gallery/axisartist/simple_axis_direction01.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_direction01_001.png + :target: /gallery/axisartist/simple_axis_direction01.html :align: center The parameter for set_axis_direction is one of ["left", "right", @@ -330,8 +335,8 @@ to the *ticklabel_direction* or *label_direction*, respectively. The rotation of ticklabels and label is anchored. -.. figure:: ../../gallery/axisartist/images/sphx_glr_axis_direction_001.png - :target: ../../gallery/axisartist/axis_direction.html +.. figure:: /gallery/axisartist/images/sphx_glr_axis_direction_001.png + :target: /gallery/axisartist/axis_direction.html :align: center On the other hand, there is a concept of "axis_direction". This is a @@ -355,8 +360,8 @@ etc, for settings suitable for "top" axis. The concept of axis direction can be more clear with curved axis. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_axis_direction_001.png - :target: ../../gallery/axisartist/demo_axis_direction.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_axis_direction_001.png + :target: /gallery/axisartist/demo_axis_direction.html :align: center The axis_direction can be adjusted in the AxisArtist level, or in the @@ -386,8 +391,8 @@ ax.axis[:].major_ticks.set_tick_out(True) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_direction03_001.png - :target: ../../gallery/axisartist/simple_axis_direction03.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_direction03_001.png + :target: /gallery/axisartist/simple_axis_direction03.html :align: center So, in summary, @@ -421,8 +426,8 @@ Alignment of TickLabels are treated specially. See below -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_ticklabel_alignment_001.png - :target: ../../gallery/axisartist/demo_ticklabel_alignment.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_ticklabel_alignment_001.png + :target: /gallery/axisartist/demo_ticklabel_alignment.html :align: center Adjusting pad @@ -436,8 +441,8 @@ ax.axis["left"].label.set_pad(10) -.. figure:: ../../gallery/axisartist/images/sphx_glr_simple_axis_pad_001.png - :target: ../../gallery/axisartist/simple_axis_pad.html +.. figure:: /gallery/axisartist/images/sphx_glr_simple_axis_pad_001.png + :target: /gallery/axisartist/simple_axis_pad.html :align: center GridHelper @@ -521,8 +526,8 @@ def inv_tr(x, y): # note that ax2.transData == tr + ax1.transData # Anything you draw in ax2 will match the ticks and grids of ax1. -.. figure:: ../../gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png - :target: ../../gallery/axisartist/demo_curvelinear_grid.html +.. figure:: /gallery/axisartist/images/sphx_glr_demo_curvelinear_grid_001.png + :target: /gallery/axisartist/demo_curvelinear_grid.html :align: center FloatingAxis diff --git a/galleries/tutorials/toolkits/mplot3d.py b/galleries/users_explain/toolkits/mplot3d.py similarity index 60% rename from galleries/tutorials/toolkits/mplot3d.py rename to galleries/users_explain/toolkits/mplot3d.py index f3ff920e036f..c50e18c5bfc6 100644 --- a/galleries/tutorials/toolkits/mplot3d.py +++ b/galleries/users_explain/toolkits/mplot3d.py @@ -1,4 +1,9 @@ """ + +.. redirect-from:: /tutorials/toolkits/mplot3d + +.. _mplot3d: + =================== The mplot3d toolkit =================== @@ -20,8 +25,8 @@ Multiple 3D subplots can be added on the same figure, as for 2D subplots. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_subplot3d_001.png - :target: ../../gallery/mplot3d/subplot3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_subplot3d_001.png + :target: /gallery/mplot3d/subplot3d.html :align: center .. versionchanged:: 3.2.0 @@ -38,8 +43,8 @@ ========== See `.Axes3D.plot` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_lines3d_001.png - :target: ../../gallery/mplot3d/lines3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_lines3d_001.png + :target: /gallery/mplot3d/lines3d.html :align: center .. _scatter3d: @@ -48,8 +53,8 @@ ============= See `.Axes3D.scatter` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_scatter3d_001.png - :target: ../../gallery/mplot3d/scatter3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_scatter3d_001.png + :target: /gallery/mplot3d/scatter3d.html :align: center .. _wireframe: @@ -58,8 +63,8 @@ =============== See `.Axes3D.plot_wireframe` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_wire3d_001.png - :target: ../../gallery/mplot3d/wire3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_wire3d_001.png + :target: /gallery/mplot3d/wire3d.html :align: center .. _surface: @@ -68,8 +73,8 @@ ============= See `.Axes3D.plot_surface` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_surface3d_001.png - :target: ../../gallery/mplot3d/surface3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_surface3d_001.png + :target: /gallery/mplot3d/surface3d.html :align: center .. _trisurface: @@ -78,8 +83,8 @@ ================= See `.Axes3D.plot_trisurf` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_trisurf3d_001.png - :target: ../../gallery/mplot3d/trisurf3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_trisurf3d_001.png + :target: /gallery/mplot3d/trisurf3d.html :align: center .. _contour3d: @@ -88,8 +93,8 @@ ============= See `.Axes3D.contour` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_contour3d_001.png - :target: ../../gallery/mplot3d/contour3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_contour3d_001.png + :target: /gallery/mplot3d/contour3d.html :align: center .. _contourf3d: @@ -98,8 +103,8 @@ ==================== See `.Axes3D.contourf` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_contourf3d_001.png - :target: ../../gallery/mplot3d/contourf3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_contourf3d_001.png + :target: /gallery/mplot3d/contourf3d.html :align: center .. versionadded:: 1.1.0 @@ -112,8 +117,8 @@ ============= See `.Axes3D.add_collection3d` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_polys3d_001.png - :target: ../../gallery/mplot3d/polys3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_polys3d_001.png + :target: /gallery/mplot3d/polys3d.html :align: center .. _bar3d: @@ -122,8 +127,8 @@ ========= See `.Axes3D.bar` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_bars3d_001.png - :target: ../../gallery/mplot3d/bars3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_bars3d_001.png + :target: /gallery/mplot3d/bars3d.html :align: center .. _quiver3d: @@ -132,16 +137,16 @@ ====== See `.Axes3D.quiver` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_quiver3d_001.png - :target: ../../gallery/mplot3d/quiver3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_quiver3d_001.png + :target: /gallery/mplot3d/quiver3d.html :align: center .. _2dcollections3d: 2D plots in 3D ============== -.. figure:: ../../gallery/mplot3d/images/sphx_glr_2dcollections3d_001.png - :target: ../../gallery/mplot3d/2dcollections3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_2dcollections3d_001.png + :target: /gallery/mplot3d/2dcollections3d.html :align: center .. _text3d: @@ -150,7 +155,7 @@ ==== See `.Axes3D.text` for API documentation. -.. figure:: ../../gallery/mplot3d/images/sphx_glr_text3d_001.png - :target: ../../gallery/mplot3d/text3d.html +.. figure:: /gallery/mplot3d/images/sphx_glr_text3d_001.png + :target: /gallery/mplot3d/text3d.html :align: center """ From fd60550c0d52df925c9a906c81d6a427bc487296 Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Tue, 7 Mar 2023 17:57:19 -0800 Subject: [PATCH 22/23] DOC: move tutorials [ci doc] --- .flake8 | 6 +- doc/api/index.rst | 2 +- doc/index.rst | 9 +- doc/users/faq/howto_faq.rst | 2 +- doc/users/prev_whats_new/whats_new_0.99.rst | 2 +- doc/users/project/history.rst | 4 +- galleries/tutorials/README.txt | 12 -- galleries/tutorials/advanced/README.txt | 7 - .../tutorials/{intermediate => }/artists.py | 6 +- .../tutorials/{introductory => }/images.py | 10 +- galleries/tutorials/index.rst | 159 ++++++++++++++++++ galleries/tutorials/intermediate/README.txt | 8 - galleries/tutorials/introductory/README.txt | 8 - .../tutorials/{introductory => }/lifecycle.py | 6 +- galleries/tutorials/provisional/README.txt | 14 -- .../tutorials/{introductory => }/pyplot.py | 6 +- galleries/users_explain/figure/index.rst | 2 +- galleries/users_explain/index.rst | 1 + lib/matplotlib/widgets.py | 16 +- pyproject.toml | 6 +- 20 files changed, 201 insertions(+), 85 deletions(-) delete mode 100644 galleries/tutorials/README.txt delete mode 100644 galleries/tutorials/advanced/README.txt rename galleries/tutorials/{intermediate => }/artists.py (99%) rename galleries/tutorials/{introductory => }/images.py (97%) create mode 100644 galleries/tutorials/index.rst delete mode 100644 galleries/tutorials/intermediate/README.txt delete mode 100644 galleries/tutorials/introductory/README.txt rename galleries/tutorials/{introductory => }/lifecycle.py (97%) delete mode 100644 galleries/tutorials/provisional/README.txt rename galleries/tutorials/{introductory => }/pyplot.py (99%) diff --git a/.flake8 b/.flake8 index ad41be9409d7..ee739cdf4231 100644 --- a/.flake8 +++ b/.flake8 @@ -60,13 +60,13 @@ per-file-ignores = galleries/users_explain/artists/transforms_tutorial.py: E402, E501 galleries/users_explain/colors/colormaps.py: E501 galleries/users_explain/colors/colors.py: E402 - galleries/tutorials/intermediate/artists.py: E402 + galleries/tutorials/artists.py: E402 galleries/users_explain/axes/constrainedlayout_guide.py: E402 galleries/users_explain/axes/legend_guide.py: E402 galleries/users_explain/axes/tight_layout_guide.py: E402 galleries/users_explain/animations/animations.py: E501 - galleries/tutorials/introductory/images.py: E501 - galleries/tutorials/introductory/pyplot.py: E402, E501 + galleries/tutorials/images.py: E501 + galleries/tutorials/pyplot.py: E402, E501 galleries/users_explain/text/annotations.py: E402, E501 galleries/users_explain/text/mathtext.py: E501 galleries/users_explain/text/text_intro.py: E402 diff --git a/doc/api/index.rst b/doc/api/index.rst index 2e8c33fa05e5..c699e7520c92 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -75,7 +75,7 @@ programmatic plot generation. Further reading: - The `matplotlib.pyplot` function reference -- :doc:`/tutorials/introductory/pyplot` +- :ref:`pyplot_tutorial` - :ref:`Pyplot examples ` .. _api-index: diff --git a/doc/index.rst b/doc/index.rst index ab811b59591c..4e593f0688dc 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -51,7 +51,7 @@ Learning resources - :ref:`Quick-start guide ` - :doc:`Plot types ` - - :ref:`Introductory tutorials ` + - :ref:`users-guide-using` - :doc:`External learning resources ` .. grid-item-card:: @@ -69,11 +69,8 @@ Learning resources Understand how Matplotlib works ^^^ - - The :ref:`users-guide-explain` in the :doc:`Users guide - ` - - Many of the :ref:`Intermediate ` and - :ref:`Advanced ` tutorials have explanatory - material + - :ref:`users-guide-explain` in the :doc:`Users guide + ` has a number of advanced topics. .. grid-item-card:: :padding: 2 diff --git a/doc/users/faq/howto_faq.rst b/doc/users/faq/howto_faq.rst index 00495d81dee2..f43494ff4f12 100644 --- a/doc/users/faq/howto_faq.rst +++ b/doc/users/faq/howto_faq.rst @@ -97,7 +97,7 @@ actually perform such a rendering and inspect the result. Find all objects in a figure of a certain type ---------------------------------------------- -Every Matplotlib artist (see :doc:`/tutorials/intermediate/artists`) has a method +Every Matplotlib artist (see :ref:`artists_tutorial`) has a method called :meth:`~matplotlib.artist.Artist.findobj` that can be used to recursively search the artist for any artists it may contain that meet some criteria (e.g., match all :class:`~matplotlib.lines.Line2D` diff --git a/doc/users/prev_whats_new/whats_new_0.99.rst b/doc/users/prev_whats_new/whats_new_0.99.rst index 0865320316e5..523e68ef1a8a 100644 --- a/doc/users/prev_whats_new/whats_new_0.99.rst +++ b/doc/users/prev_whats_new/whats_new_0.99.rst @@ -13,7 +13,7 @@ New documentation Jae-Joon Lee has written two new guides :ref:`legend_guide` and :ref:`plotting-guide-annotation`. Michael Sarahan has written -:doc:`/tutorials/introductory/images`. John Hunter has written two new tutorials on +:ref:`image_tutorial`. John Hunter has written two new tutorials on working with paths and transformations: :ref:`paths` and :ref:`transforms_tutorial`. diff --git a/doc/users/project/history.rst b/doc/users/project/history.rst index 3291d7e43f8b..18a94793736f 100644 --- a/doc/users/project/history.rst +++ b/doc/users/project/history.rst @@ -68,10 +68,10 @@ The Matplotlib code is conceptually divided into three parts: the *pylab interface* is the set of functions provided by :mod:`pylab` which allow the user to create plots with code quite similar to MATLAB figure generating code -(:doc:`/tutorials/introductory/pyplot`). The *Matplotlib frontend* or *Matplotlib +(:ref:`pyplot_tutorial`). The *Matplotlib frontend* or *Matplotlib API* is the set of classes that do the heavy lifting, creating and managing figures, text, lines, plots and so on -(:doc:`/tutorials/intermediate/artists`). This is an abstract interface that knows +(:ref:`artists_tutorial`). This is an abstract interface that knows nothing about output. The *backends* are device-dependent drawing devices, aka renderers, that transform the frontend representation to hardcopy or a display device (:ref:`what-is-a-backend`). Example diff --git a/galleries/tutorials/README.txt b/galleries/tutorials/README.txt deleted file mode 100644 index da744b3224c7..000000000000 --- a/galleries/tutorials/README.txt +++ /dev/null @@ -1,12 +0,0 @@ -.. _tutorials: - -Tutorials -========= - -This page contains more in-depth guides for using Matplotlib. -It is broken up into beginner, intermediate, and advanced sections, -as well as sections covering specific topics. - -For shorter examples, see our :ref:`examples page `. -You can also find :ref:`external resources ` and -a :ref:`FAQ ` in our :ref:`user guide `. diff --git a/galleries/tutorials/advanced/README.txt b/galleries/tutorials/advanced/README.txt deleted file mode 100644 index 47292163be06..000000000000 --- a/galleries/tutorials/advanced/README.txt +++ /dev/null @@ -1,7 +0,0 @@ -.. _tutorials-advanced: - -Advanced --------- - -These tutorials cover advanced topics for experienced Matplotlib -users and developers. diff --git a/galleries/tutorials/intermediate/artists.py b/galleries/tutorials/artists.py similarity index 99% rename from galleries/tutorials/intermediate/artists.py rename to galleries/tutorials/artists.py index 9d3b5305b5d4..46303372d7ae 100644 --- a/galleries/tutorials/intermediate/artists.py +++ b/galleries/tutorials/artists.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/intermediate/artists + +.. _artists_tutorial: + =============== Artist tutorial =============== @@ -716,6 +720,6 @@ class in the Matplotlib API, and the one you will be working with most # dollar signs and colors them green on the right side of the yaxis. # # -# .. include:: ../../gallery/ticks/dollar_ticks.rst +# .. include:: ../gallery/ticks/dollar_ticks.rst # :start-after: .. redirect-from:: /gallery/pyplots/dollar_ticks # :end-before: .. admonition:: References diff --git a/galleries/tutorials/introductory/images.py b/galleries/tutorials/images.py similarity index 97% rename from galleries/tutorials/introductory/images.py rename to galleries/tutorials/images.py index 2e6b6376f723..24ab2bf8f495 100644 --- a/galleries/tutorials/introductory/images.py +++ b/galleries/tutorials/images.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/introductory/images + +.. _image_tutorial: + ============== Image tutorial ============== @@ -65,7 +69,7 @@ # # Here's the image we're going to play with: # -# .. image:: ../../_static/stinkbug.png +# .. image:: ../_static/stinkbug.png # # It's a 24-bit RGB PNG image (8 bits for each of R, G, B). Depending # on where you get your data, the other kinds of image that you'll most @@ -78,7 +82,7 @@ # convert the `PIL.Image.Image` object into an 8-bit (``dtype=uint8``) numpy # array. -img = np.asarray(Image.open('../../../doc/_static/stinkbug.png')) +img = np.asarray(Image.open('../../doc/_static/stinkbug.png')) print(repr(img)) # %% @@ -227,7 +231,7 @@ # We'll use the Pillow library that we used to load the image also to resize # the image. -img = Image.open('../../../doc/_static/stinkbug.png') +img = Image.open('../../doc/_static/stinkbug.png') img.thumbnail((64, 64)) # resizes image in-place imgplot = plt.imshow(img) diff --git a/galleries/tutorials/index.rst b/galleries/tutorials/index.rst new file mode 100644 index 000000000000..899b3bbcc64e --- /dev/null +++ b/galleries/tutorials/index.rst @@ -0,0 +1,159 @@ +.. _tutorials: + +Tutorials +========= + +This page contains a few tutorials for using Matplotlib. For the old tutorials, see :ref:`below `. + +For shorter examples, see our :ref:`examples page `. +You can also find :ref:`external resources ` and +a :ref:`FAQ ` in our :ref:`user guide `. + + +.. raw:: html + +
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_pyplot_thumb.png + :alt: Pyplot tutorial + + :ref:`sphx_glr_tutorials_pyplot.py` + +.. raw:: html + +
Pyplot tutorial
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_images_thumb.png + :alt: Image tutorial + + :ref:`sphx_glr_tutorials_images.py` + +.. raw:: html + +
Image tutorial
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_lifecycle_thumb.png + :alt: The Lifecycle of a Plot + + :ref:`sphx_glr_tutorials_lifecycle.py` + +.. raw:: html + +
The Lifecycle of a Plot
+
+ + +.. raw:: html + +
+ +.. only:: html + + .. image:: /tutorials/images/thumb/sphx_glr_artists_thumb.png + :alt: Artist tutorial + + :ref:`sphx_glr_tutorials_artists.py` + +.. raw:: html + +
Artist tutorial
+
+ + +.. raw:: html + +
+ + +.. toctree:: + :hidden: + + /tutorials/pyplot + /tutorials/images + /tutorials/lifecycle + /tutorials/artists + +.. only:: html + + .. container:: sphx-glr-footer sphx-glr-footer-gallery + + .. container:: sphx-glr-download sphx-glr-download-python + + :download:`Download all examples in Python source code: tutorials_python.zip ` + + .. container:: sphx-glr-download sphx-glr-download-jupyter + + :download:`Download all examples in Jupyter notebooks: tutorials_jupyter.zip ` + + + +.. _user_guide_tutorials: + +User guide tutorials +-------------------- + +Many of our tutorials were moved from this section to :ref:`users-guide-explain`: + +Introductory +~~~~~~~~~~~~ + +- :ref:`quick_start` +- :ref:`customizing` +- :ref:`animations` + +Intermediate +~~~~~~~~~~~~ + +- :ref:`legend_guide` +- :ref:`color_cycle` +- :ref:`constrainedlayout_guide` +- :ref:`tight_layout_guide` +- :ref:`arranging_axes` +- :ref:`autoscale` +- :ref:`imshow_extent` + +Advanced +~~~~~~~~ + +- :ref:`blitting` +- :ref:`paths` +- :ref:`patheffects_guide` +- :ref:`transforms_tutorial` + +Colors +~~~~~~ + +See :ref:`tutorials-colors`. + +Text +~~~~ + +See :ref:`tutorials-text`. + +Toolkits +~~~~~~~~ + +See :ref:`tutorials-toolkits`. diff --git a/galleries/tutorials/intermediate/README.txt b/galleries/tutorials/intermediate/README.txt deleted file mode 100644 index 5ae0dbd83c3b..000000000000 --- a/galleries/tutorials/intermediate/README.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. _tutorials-intermediate: - -Intermediate ------------- - -These tutorials cover some of the more complicated classes and functions -in Matplotlib. They can be useful for particular custom and complex -visualizations. diff --git a/galleries/tutorials/introductory/README.txt b/galleries/tutorials/introductory/README.txt deleted file mode 100644 index f51300a2a840..000000000000 --- a/galleries/tutorials/introductory/README.txt +++ /dev/null @@ -1,8 +0,0 @@ -.. _tutorials-introductory: - -Introductory -------------- - -These tutorials cover the basics of creating visualizations with -Matplotlib, as well as some best-practices in using the package -effectively. diff --git a/galleries/tutorials/introductory/lifecycle.py b/galleries/tutorials/lifecycle.py similarity index 97% rename from galleries/tutorials/introductory/lifecycle.py rename to galleries/tutorials/lifecycle.py index 5613d52cb2ea..9df59a5d229f 100644 --- a/galleries/tutorials/introductory/lifecycle.py +++ b/galleries/tutorials/lifecycle.py @@ -1,4 +1,6 @@ """ +.. redirect-from:: /tutorials/introductory/lifecycle + ======================= The Lifecycle of a Plot ======================= @@ -27,8 +29,8 @@ :class:`axes.Axes` to build up the visualization in an instance of :class:`figure.Figure`. In the implicit interface, inspired by and modeled on MATLAB, we use a global state-based interface which is encapsulated in the -:mod:`.pyplot` module to plot to the "current Axes". See the :doc:`pyplot -tutorials ` for a more in-depth look at the +:mod:`.pyplot` module to plot to the "current Axes". See the :ref:`pyplot +tutorials ` for a more in-depth look at the pyplot interface. Most of the terms are straightforward but the main thing to remember diff --git a/galleries/tutorials/provisional/README.txt b/galleries/tutorials/provisional/README.txt deleted file mode 100644 index cf2296f05369..000000000000 --- a/galleries/tutorials/provisional/README.txt +++ /dev/null @@ -1,14 +0,0 @@ -.. _tutorials-provisional: - -Provisional ------------ - -These tutorials cover proposed APIs of any complexity. These are here -to document features that we have released, but want to get user -feedback on before committing to them. Please have a look, try them -out and give us feedback on `gitter -`__, `discourse -`__, or the `the mailing list -`__! But, -be aware that we may change the APIs without warning in subsequent -versions. diff --git a/galleries/tutorials/introductory/pyplot.py b/galleries/tutorials/pyplot.py similarity index 99% rename from galleries/tutorials/introductory/pyplot.py rename to galleries/tutorials/pyplot.py index ae59437a8d8d..b7f9245190d0 100644 --- a/galleries/tutorials/introductory/pyplot.py +++ b/galleries/tutorials/pyplot.py @@ -1,4 +1,8 @@ """ +.. redirect-from:: /tutorials/introductory/pyplot + +.. _pyplot_tutorial: + =============== Pyplot tutorial =============== @@ -307,7 +311,7 @@ def f(t): # it annoying that states (specifically the current image, figure and axes) # are being maintained for you behind the scenes, don't despair: this is just a thin # stateful wrapper around an object-oriented API, which you can use -# instead (see :doc:`/tutorials/intermediate/artists`) +# instead (see :ref:`artists_tutorial`) # # If you are making lots of figures, you need to be aware of one # more thing: the memory required for a figure is not completely diff --git a/galleries/users_explain/figure/index.rst b/galleries/users_explain/figure/index.rst index 991bd9032e39..5e2ecc17d2c1 100644 --- a/galleries/users_explain/figure/index.rst +++ b/galleries/users_explain/figure/index.rst @@ -111,7 +111,7 @@ Creating Figures ================ By far the most common way to create a figure is using the -:doc:`pyplot ` interface. As noted in +:ref:`pyplot ` interface. As noted in :ref:`api_interfaces`, the pyplot interface serves two purposes. One is to spin up the Backend and keep track of GUI windows. The other is a global state for Axes and Artists that allow a short-form API to plotting methods. In the diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 0fa5c8a15f07..56b7004b18be 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -1,4 +1,5 @@ .. _users-guide-explain: +.. _users-guide-using: .. redirect-from:: /users/explain diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py index c8209d1616a4..7aedd67ef38c 100644 --- a/lib/matplotlib/widgets.py +++ b/lib/matplotlib/widgets.py @@ -189,7 +189,7 @@ def __init__(self, ax, label, image=None, Use blitting for faster drawing if supported by the backend. See the tutorial :ref:`blitting` for details. - .. versionadded:: 3.7 + .. versionadded:: 3.7 """ super().__init__(ax) @@ -1030,13 +1030,10 @@ def __init__(self, ax, labels, actives=None, *, useblit=True, same length as *labels*. If not given, all buttons are unchecked. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. -<<<<<<< HEAD - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. .. versionadded:: 3.7 -======= - See the tutorial :ref:`blitting` for details. ->>>>>>> b6f353389a (DOC: fix flake8 [ci doc]) + label_props : dict, optional Dictionary of `.Text` properties to be used for the labels. @@ -1641,13 +1638,10 @@ def __init__(self, ax, labels, active=0, activecolor=None, *, specified here or in *radio_props*. useblit : bool, default: True Use blitting for faster drawing if supported by the backend. -<<<<<<< HEAD - See the tutorial :doc:`/tutorials/advanced/blitting` for details. + See the tutorial :ref:`blitting` for details. .. versionadded:: 3.7 -======= - See the tutorial :ref:`blitting` for details. ->>>>>>> b6f353389a (DOC: fix flake8 [ci doc]) + label_props : dict or list of dict, optional Dictionary of `.Text` properties to be used for the labels. diff --git a/pyproject.toml b/pyproject.toml index cff0fe04818a..80fa56e71454 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -117,13 +117,13 @@ convention = "numpy" "galleries/users_explain/artists/transforms_tutorial.py" = ["E402", "E501"] "galleries/users_explain/colors/colormaps.py" = ["E501"] "galleries/users_explain/colors/colors.py" = ["E402"] -"galleries/tutorials/intermediate/artists.py" = ["E402"] +"galleries/tutorials/artists.py" = ["E402"] "galleries/users_explain/axes/constrainedlayout_guide.py" = ["E402"] "galleries/users_explain/axes/legend_guide.py" = ["E402"] "galleries/users_explain/axes/tight_layout_guide.py" = ["E402"] "galleries/users_explain/animations/animation.py" = ["E501"] -"galleries/tutorials/introductory/images.py" = ["E501"] -"galleries/tutorials/introductory/pyplot.py" = ["E402", "E501"] +"galleries/tutorials/images.py" = ["E501"] +"galleries/tutorials/pyplot.py" = ["E402", "E501"] "galleries/users_explain/text/annotations.py" = ["E402", "E501"] "galleries/users_explain/text/mathtext.py" = ["E501"] "galleries/users_explain/text/text_intro.py" = ["E402"] From cb8e8724bcb637d2a5d558721c5292384bf180ec Mon Sep 17 00:00:00 2001 From: Jody Klymak Date: Fri, 10 Mar 2023 16:19:32 -0800 Subject: [PATCH 23/23] DOC: a bit more about ticks for axes --- galleries/users_explain/axes/index.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/galleries/users_explain/axes/index.rst b/galleries/users_explain/axes/index.rst index 57f893e0e18f..8bcf51add979 100644 --- a/galleries/users_explain/axes/index.rst +++ b/galleries/users_explain/axes/index.rst @@ -147,7 +147,18 @@ Other important methods set the extent on the axes (`~.axes.Axes.set_xlim`, `~.a The Axes class also has helpers to deal with Axis ticks and their labels. Most straight-forward is `~.axes.Axes.set_xticks` and `~.axes.Axes.set_yticks` which manually set the tick locations and optionally their labels. Minor ticks can be toggled with `~.axes.Axes.minorticks_on` or `~.axes.Axes.minorticks_off`. -Setting scales and controlling the Axis can be highly customized beyond these Axes-level helpers. An introduction to these methods can be found in :ref:`users_axis`, or the API reference for `.axis.Axis`. +Many aspects of Axes ticks and tick labeling can be adjusted using `~.axes.Axes.tick_params`. For instance, to label the top of the axes instead of the bottom,color the ticks red, and color the ticklabels green: + +.. plot:: + :include-source: + + fig, ax = plt.subplots(figsize=(4, 2.5)) + ax.plot(np.arange(10)) + ax.tick_params(top=True, labeltop=True, color='red', axis='x', + labelcolor='green') + + +More fine-grained control on ticks, setting scales, and controlling the Axis can be highly customized beyond these Axes-level helpers. An introduction to these methods can be found in :ref:`users_axis`, or the API reference for `.axis.Axis`. Axes layout -----------