Clarify tutorial about style sheets and rcParams

andthum · andthum · commit f3af5c6f62a5 · 2021-08-09T11:45:48.000+02:00
diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py
@@ -1,24 +1,40 @@
 """
 .. redirect-from:: /users/customizing
 
+=====================================================
 Customizing Matplotlib with style sheets and rcParams
 =====================================================
 
 Tips for customizing the properties and default styles of Matplotlib.
+There are basically 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>`.
+
+.. _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, just add:
 """
 
 import numpy as np
@@ -104,15 +120,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 +180,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 +214,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 +227,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
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+# --------------------------
 #
 # .. literalinclude:: ../../../lib/matplotlib/mpl-data/matplotlibrc
 #
