From f32d0f18bf20075129f55f339e427fadd1470ed5 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sun, 5 Nov 2023 22:26:26 +0100 Subject: [PATCH] Backport PR #27268: Copy-edit various examples. --- galleries/examples/color/README.txt | 3 +-- galleries/examples/color/named_colors.py | 2 +- .../images_contours_and_fields/image_demo.py | 8 +++----- .../images_contours_and_fields/pcolor_demo.py | 12 +++++------- .../text_labels_and_annotations/accented_text.py | 6 +++--- .../annotation_demo.py | 2 +- .../text_labels_and_annotations/font_file.py | 6 +++--- .../text_labels_and_annotations/legend_demo.py | 2 -- .../axes/constrainedlayout_guide.py | 8 +++----- galleries/users_explain/axes/legend_guide.py | 11 ++++------- .../users_explain/axes/tight_layout_guide.py | 16 ++++++---------- .../colors/colormap-manipulation.py | 15 ++++++--------- galleries/users_explain/colors/colormaps.py | 6 +++--- galleries/users_explain/text/text_intro.py | 6 +++--- 14 files changed, 42 insertions(+), 61 deletions(-) diff --git a/galleries/examples/color/README.txt b/galleries/examples/color/README.txt index 4bcdb526f4d4..4b8b3bc4b751 100644 --- a/galleries/examples/color/README.txt +++ b/galleries/examples/color/README.txt @@ -3,6 +3,5 @@ Color ===== -For more in-depth information about the colormaps available in matplotlib -as well as a description of their properties, +For a description of the colormaps available in Matplotlib, see the :ref:`colormaps tutorial `. diff --git a/galleries/examples/color/named_colors.py b/galleries/examples/color/named_colors.py index 9ae4ec4957f3..d9a7259da773 100644 --- a/galleries/examples/color/named_colors.py +++ b/galleries/examples/color/named_colors.py @@ -3,7 +3,7 @@ List of named colors ==================== -This plots a list of the named colors supported in matplotlib. +This plots a list of the named colors supported by Matplotlib. For more information on colors in matplotlib see * the :ref:`colors_def` tutorial; diff --git a/galleries/examples/images_contours_and_fields/image_demo.py b/galleries/examples/images_contours_and_fields/image_demo.py index 884e68172698..213b6cdd28c2 100644 --- a/galleries/examples/images_contours_and_fields/image_demo.py +++ b/galleries/examples/images_contours_and_fields/image_demo.py @@ -1,9 +1,7 @@ """ -========== -Image demo -========== - -Many ways to plot images in Matplotlib. +======================== +Many ways to plot images +======================== The most common way to plot images in Matplotlib is with `~.axes.Axes.imshow`. The following examples demonstrate much of the diff --git a/galleries/examples/images_contours_and_fields/pcolor_demo.py b/galleries/examples/images_contours_and_fields/pcolor_demo.py index a783c83409df..7a8ef35caf96 100644 --- a/galleries/examples/images_contours_and_fields/pcolor_demo.py +++ b/galleries/examples/images_contours_and_fields/pcolor_demo.py @@ -1,13 +1,11 @@ """ -=========== -Pcolor demo -=========== +============= +pcolor images +============= -Generating images with `~.axes.Axes.pcolor`. - -Pcolor allows you to generate 2D image-style plots. Below we will show how -to do so in Matplotlib. +`~.Axes.pcolor` generates 2D image-style plots, as illustrated below. """ + import matplotlib.pyplot as plt import numpy as np diff --git a/galleries/examples/text_labels_and_annotations/accented_text.py b/galleries/examples/text_labels_and_annotations/accented_text.py index f57b19532a43..7ff080afefd9 100644 --- a/galleries/examples/text_labels_and_annotations/accented_text.py +++ b/galleries/examples/text_labels_and_annotations/accented_text.py @@ -1,7 +1,7 @@ r""" -================================= -Using accented text in Matplotlib -================================= +============= +Accented text +============= Matplotlib supports accented characters via TeX mathtext or Unicode. diff --git a/galleries/examples/text_labels_and_annotations/annotation_demo.py b/galleries/examples/text_labels_and_annotations/annotation_demo.py index 8b310a7a1865..26f3b80bf203 100644 --- a/galleries/examples/text_labels_and_annotations/annotation_demo.py +++ b/galleries/examples/text_labels_and_annotations/annotation_demo.py @@ -3,7 +3,7 @@ Annotating Plots ================ -The following examples show how it is possible to annotate plots in Matplotlib. +The following examples show ways to annotate plots in Matplotlib. 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 diff --git a/galleries/examples/text_labels_and_annotations/font_file.py b/galleries/examples/text_labels_and_annotations/font_file.py index 8242b57839aa..b4a58808d716 100644 --- a/galleries/examples/text_labels_and_annotations/font_file.py +++ b/galleries/examples/text_labels_and_annotations/font_file.py @@ -1,7 +1,7 @@ r""" -=================================== -Using a ttf font file in Matplotlib -=================================== +==================== +Using ttf font files +==================== Although it is usually not a good idea to explicitly point to a single ttf file for a font instance, you can do so by passing a `pathlib.Path` instance as the diff --git a/galleries/examples/text_labels_and_annotations/legend_demo.py b/galleries/examples/text_labels_and_annotations/legend_demo.py index a425d39b7d8f..2f550729837e 100644 --- a/galleries/examples/text_labels_and_annotations/legend_demo.py +++ b/galleries/examples/text_labels_and_annotations/legend_demo.py @@ -3,8 +3,6 @@ Legend Demo =========== -Plotting legends in Matplotlib. - There are many ways to create and customize legends in Matplotlib. Below we'll show a few examples for how to do so. diff --git a/galleries/users_explain/axes/constrainedlayout_guide.py b/galleries/users_explain/axes/constrainedlayout_guide.py index 260a4f76bf71..4581f5f67808 100644 --- a/galleries/users_explain/axes/constrainedlayout_guide.py +++ b/galleries/users_explain/axes/constrainedlayout_guide.py @@ -40,15 +40,13 @@ .. warning:: - Calling ``plt.tight_layout()`` will turn off *constrained layout*! + Calling `~.pyplot.tight_layout` will turn off *constrained layout*! Simple example ============== -In Matplotlib, the location of Axes (including subplots) are specified in -normalized figure coordinates. It can happen that your axis labels or titles -(or sometimes even ticklabels) go outside the figure area, and are thus -clipped. +With the default Axes positioning, the axes title, axis labels, or tick labels +can sometimes go outside the figure area, and thus get clipped. """ # sphinx_gallery_thumbnail_number = 18 diff --git a/galleries/users_explain/axes/legend_guide.py b/galleries/users_explain/axes/legend_guide.py index 9900b0aa4bdd..3b138fe8ada3 100644 --- a/galleries/users_explain/axes/legend_guide.py +++ b/galleries/users_explain/axes/legend_guide.py @@ -7,13 +7,10 @@ Legend guide ============ -Generating legends flexibly in Matplotlib. - .. currentmodule:: matplotlib.pyplot -This legend guide is an extension of the documentation available at -:func:`~matplotlib.pyplot.legend` - please ensure you are familiar with -contents of that documentation before proceeding with this guide. +This legend guide extends the `~.Axes.legend` docstring - +please read it before proceeding with this guide. This guide makes use of some common terms, which are documented here for clarity: @@ -62,8 +59,8 @@ line_down, = ax.plot([3, 2, 1], label='Line 1') ax.legend(handles=[line_up, line_down]) -In some cases, it is not possible to set the label of the handle, so it is -possible to pass through the list of labels to :func:`legend`:: +In the rare case where the labels cannot directly be set on the handles, they +can also be directly passed to :func:`legend`:: fig, ax = plt.subplots() line_up, = ax.plot([1, 2, 3], label='Line 2') diff --git a/galleries/users_explain/axes/tight_layout_guide.py b/galleries/users_explain/axes/tight_layout_guide.py index 42c227b2e360..8525b9773f91 100644 --- a/galleries/users_explain/axes/tight_layout_guide.py +++ b/galleries/users_explain/axes/tight_layout_guide.py @@ -17,15 +17,11 @@ An alternative to *tight_layout* is :ref:`constrained_layout `. - -Simple Example +Simple example ============== -In matplotlib, the location of axes (including subplots) are specified in -normalized figure coordinates. It can happen that your axis labels or -titles (or sometimes even ticklabels) go outside the figure area, and are thus -clipped. - +With the default Axes positioning, the axes title, axis labels, or tick labels +can sometimes go outside the figure area, and thus get clipped. """ # sphinx_gallery_thumbnail_number = 7 @@ -190,8 +186,8 @@ def example_plot(ax, fontsize=12): # %% # You may provide an optional *rect* parameter, which specifies the bounding -# box that the subplots will be fit inside. The coordinates must be in -# normalized figure coordinates and the default is (0, 0, 1, 1). +# box that the subplots will be fit inside. The coordinates are in +# normalized figure coordinates and default to (0, 0, 1, 1) (the whole figure). fig = plt.figure() @@ -245,7 +241,7 @@ def example_plot(ax, fontsize=12): # Use with AxesGrid1 # ================== # -# While limited, :mod:`mpl_toolkits.axes_grid1` is also supported. +# Limited support for :mod:`mpl_toolkits.axes_grid1` is provided. from mpl_toolkits.axes_grid1 import Grid diff --git a/galleries/users_explain/colors/colormap-manipulation.py b/galleries/users_explain/colors/colormap-manipulation.py index 88e4c5befaf0..87269b87befa 100644 --- a/galleries/users_explain/colors/colormap-manipulation.py +++ b/galleries/users_explain/colors/colormap-manipulation.py @@ -3,9 +3,9 @@ .. _colormap-manipulation: -******************************** -Creating Colormaps in Matplotlib -******************************** +****************** +Creating Colormaps +****************** Matplotlib has a number of built-in colormaps accessible via `.matplotlib.colormaps`. There are also external libraries like @@ -13,17 +13,15 @@ .. _palettable: https://jiffyclub.github.io/palettable/ -However, we often want to create or manipulate colormaps in Matplotlib. +However, we may also want to create or manipulate our own colormaps. This can be done using the class `.ListedColormap` or `.LinearSegmentedColormap`. -Seen from the outside, both colormap classes map values between 0 and 1 to -a bunch of colors. There are, however, slight differences, some of which are -shown in the following. +Both colormap classes map values between 0 and 1 to colors. There are however +differences, as explained below. Before manually creating or manipulating colormaps, let us first see how we can obtain colormaps and their colors from existing colormap classes. - Getting colormaps and accessing their values ============================================ @@ -32,7 +30,6 @@ 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. - """ import matplotlib.pyplot as plt diff --git a/galleries/users_explain/colors/colormaps.py b/galleries/users_explain/colors/colormaps.py index 92b56d298976..b5db551cb5b5 100644 --- a/galleries/users_explain/colors/colormaps.py +++ b/galleries/users_explain/colors/colormaps.py @@ -3,9 +3,9 @@ .. _colormaps: -******************************** -Choosing Colormaps in Matplotlib -******************************** +****************** +Choosing Colormaps +****************** Matplotlib has a number of built-in colormaps accessible via `.matplotlib.colormaps`. There are also external libraries that diff --git a/galleries/users_explain/text/text_intro.py b/galleries/users_explain/text/text_intro.py index 54fcb00c7a86..948545667fa9 100644 --- a/galleries/users_explain/text/text_intro.py +++ b/galleries/users_explain/text/text_intro.py @@ -4,9 +4,9 @@ .. _text_intro: -======================== -Text in Matplotlib Plots -======================== +================== +Text in Matplotlib +================== Introduction to plotting and working with text in Matplotlib.