Merge pull request #8518 from Rufflewind/doc

phobson · web-flow · commit c3a440dea52c · 2017-04-20T09:52:29.000-07:00
DOC: Discourage omitting backend in matplotlibrc
diff --git a/doc/users/customizing.rst b/doc/users/customizing.rst
@@ -156,6 +156,9 @@ locations, in the following order:
    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.
+
 To display where the currently active :file:`matplotlibrc` file was
 loaded from, one can do the following::
 
@@ -164,6 +167,12 @@ loaded from, one can do the following::
   '/home/foo/.config/matplotlib/matplotlibrc'
 
 See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.
+Although all parameters are optional, you should almost always set the
+`backend` or else matplotlib will choose `Agg`, a *non-interactive* backend.
+This can lead to unexpected behavior, since if you do not have a
+:file:`matplotlibrc` file, it would normally fall back to
+:file:`{INSTALL}/matplotlib/mpl-data/matplotlibrc`, which is often set to an
+interactive backend by the package maintainer.
 
 .. _matplotlibrc-sample:
 
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -35,6 +35,9 @@
 # You can also deploy your own backend outside of matplotlib by
 # referring to the module name (which must be in the PYTHONPATH) as
 # 'module://my_backend'.
+#
+# If you omit this parameter, it will always default to "Agg", which is a
+# non-interactive backend.
 backend      : $TEMPLATE_BACKEND
 
 # If you are using the Qt4Agg backend, you can choose here
