Clarify tutorial about style sheets and rcParams

andthum · andthum · commit 08bb99dc31d4 · 2021-08-10T09:20:46.000+02:00
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
@@ -351,7 +351,7 @@ def __init__(self, xy, s, size=None, prop=None,
         prop : `matplotlib.font_manager.FontProperties`, optional
             Font property. If not provided, will use a default
             ``FontProperties`` with parameters from the
-            :ref:`rcParams <matplotlib-rcparams>`.
+            :ref:`rcParams<customizing-with-dynamic-rc-settings>`.
 
         _interpolation_steps : int, optional
             (Currently ignored)
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -22,7 +22,8 @@
 
       plt.subplots(constrained_layout=True)
 
-* activate it via :ref:`rcParams<matplotlib-rcparams>`, like::
+* activate it via :ref:`rcParams<customizing-with-dynamic-rc-settings>`,
+  like::
 
       plt.rcParams['figure.constrained_layout.use'] = True
 
@@ -306,9 +307,9 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # rcParams
 # ========
 #
-# There are five :ref:`rcParams<matplotlib-rcparams>` that can be set,
-# either in a script or in the :file:`matplotlibrc` file.
-# They all have the prefix ``figure.constrained_layout``:
+# There are five :ref:`rcParams<customizing-with-dynamic-rc-settings>`
+# that can be set, either in a script or in the :file:`matplotlibrc`
+# file. They all have the prefix ``figure.constrained_layout``:
 #
 # - *use*: Whether to use constrained_layout. Default is False
 # - *w_pad*, *h_pad*:    Padding around axes objects.
diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py
@@ -1,24 +1,43 @@
 """
 .. redirect-from:: /users/customizing
 
+=====================================================
 Customizing Matplotlib with style sheets and rcParams
 =====================================================
 
 Tips for customizing the properties and default styles of Matplotlib.
+There are three ways to customize Matplotlib:
+
+    1. :ref:`Using style sheets<customizing-with-style-sheets>`.
+    2. :ref:`Setting rcParams at runtime<customizing-with-dynamic-rc-settings>`.
+    3. :ref:`Changing your matplotlibrc file<customizing-with-matplotlibrc-files>`.
+
+Style sheets take precedence over :file:`matplotlibrc` files and setting
+rcParams at runtime takes precedence over style sheets.
+
+.. _customizing-with-style-sheets:
 
 Using style sheets
-------------------
+==================
 
 The :mod:`.style` package adds support for easy-to-switch plotting
-"styles" with the same parameters as a :ref:`matplotlib rc
+"styles" with the same parameters (rcParams) as a :ref:`matplotlibrc
 <customizing-with-matplotlibrc-files>` file (which is read at startup to
-configure Matplotlib).
+configure Matplotlib). However, in a style sheet you can only set
+rcParams that are related to the actual style of a plot. Other rcParams,
+like *backend*, will be ignored. This behavior is different fom the
+:file:`matplotlibrc` file, which supports all rcParams. In this way,
+style sheets are portable between different machines without having to
+worry about dependencies which might or might not be installed on
+another machine. For a full list of rcParams see `matplotlib.rcParams`.
+For a list of rcParams that are ignored in style sheets see
+`matplotlib.style.use`.
 
 There are a number of pre-defined styles :doc:`provided by Matplotlib
 </gallery/style_sheets/style_sheets_reference>`. For
 example, there's a pre-defined style called "ggplot", which emulates the
-aesthetics of ggplot_ (a popular plotting package for R_). To use this style,
-just add:
+aesthetics of ggplot_ (a popular plotting package for R_). To use this
+style, add:
 """
 
 import numpy as np
@@ -104,15 +123,10 @@
 plt.show()
 
 ###############################################################################
-# .. _matplotlib-rcparams:
-#
-# Matplotlib rcParams
-# ===================
-#
 # .. _customizing-with-dynamic-rc-settings:
 #
 # Dynamic rc settings
-# -------------------
+# ===================
 #
 # You can also dynamically change the default rc settings in a python script or
 # interactively from the python shell. All of the rc settings are stored in a
@@ -169,14 +183,13 @@ def plotting_function():
 # .. _customizing-with-matplotlibrc-files:
 #
 # The :file:`matplotlibrc` file
-# -----------------------------
+# =============================
 #
 # Matplotlib uses :file:`matplotlibrc` configuration files to customize all
 # kinds of properties, which we call 'rc settings' or 'rc parameters'. You can
 # control the defaults of almost every property in Matplotlib: figure size and
 # DPI, line width, color and style, axes, axis and grid properties, text and
-# font properties and so on. When a URL or path is not specified with a call to
-# ``style.use('<path>/<style-name>.mplstyle')``, Matplotlib looks for
+# font properties and so on. Matplotlib looks for
 # :file:`matplotlibrc` in four locations, in the following order:
 #
 # 1. :file:`matplotlibrc` in the current working directory, usually used for
@@ -204,8 +217,11 @@ def plotting_function():
 #    your customizations to be saved, please move this file to your
 #    user-specific matplotlib directory.
 #
-# Once a :file:`matplotlibrc` file has been found, it will *not* search any of
-# the other paths.
+# Once a :file:`matplotlibrc` file has been found, it will *not* search
+# any of the other paths. When a
+# :ref:`style sheet<customizing-with-style-sheets>` is given with
+# ``style.use('<path>/<style-name>.mplstyle')``, settings specified in
+# the style sheet take precedence over the :file:`matplotlibrc` file.
 #
 # To display where the currently active :file:`matplotlibrc` file was
 # loaded from, one can do the following::
@@ -214,12 +230,13 @@ def plotting_function():
 #   >>> matplotlib.matplotlib_fname()
 #   '/home/foo/.config/matplotlib/matplotlibrc'
 #
-# See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.
+# See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`
+# and see `matplotlib.rcParams` for a full list of configurable rcParams.
 #
 # .. _matplotlibrc-sample:
 #
-# A sample matplotlibrc file
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+# The default :file:`matplotlibrc` file
+# -------------------------------------
 #
 # .. literalinclude:: ../../../lib/matplotlib/mpl-data/matplotlibrc
 #
