Update style docs

Author: timhoffm

doc/api/style_api.rst

@@ -2,20 +2,32 @@
 ``matplotlib.style``
 ********************
 
-.. seealso::
+Styles are predefined sets of `.rcParams` that define the visual appearance of
+a plot.
 
-   Examples of using style sheets with :func:`matplotlib.style.use` can be found at :doc:`/gallery/style_sheets/style_sheets_reference`.
+:doc:`/tutorials/introductory/customizing` describes the mechanism and usage
+of styles.
+
+The :doc:`/gallery/style_sheets/style_sheets_reference` gives an overview of
+the builtin styles.
 
 .. automodule:: matplotlib.style
    :members:
    :undoc-members:
    :show-inheritance:
    :imported-members:
 
+.. imported variables have to be specified explicitly due to
+   https://github.com/sphinx-doc/sphinx/issues/6607
+
 .. data:: matplotlib.style.library
 
-   Dictionary of available styles
+   A dict mapping from style name to `.RcParams` defining that style.
+
+   This is meant to be read-only. Use `.reload_library` to update.
 
 .. data:: matplotlib.style.available
 
-   List of available styles
+   List of the names of the available styles.
+
+   This is meant to be read-only. Use `.reload_library` to update.

lib/matplotlib/style/core.py

@@ -70,6 +70,11 @@ def use(style):
     The style name of 'default' is reserved for reverting back to
     the default style settings.
 
+    .. note::
+
+       This updates the `.rcParams` with the settings from the style.
+       `.rcParams` not defined in the style are kept.
+
     Parameters
     ----------
     style : str, dict, Path or list
@@ -167,7 +172,7 @@ def iter_user_libraries():
 
 
 def update_user_library(library):
-    """Update style library with user-defined rc files"""
+    """Update style library with user-defined rc files."""
     for stylelib_path in iter_user_libraries():
         styles = read_style_directory(stylelib_path)
         update_nested_dict(library, styles)
@@ -215,11 +220,12 @@ def update_nested_dict(main_dict, new_dict):
 _base_library = load_base_library()
 
 library = None
+
 available = []
 
 
 def reload_library():
-    """Reload style library."""
+    """Reload the style library."""
     global library
     library = update_user_library(_base_library)
     available[:] = sorted(library.keys())