SF.net SVN: matplotlib: [5447] trunk/matplotlib/doc/users/customizing.rst

[<ds...@us...>]

Revision: 5447
          http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5447&view=rev
Author:   dsdale
Date:     2008-06-09 14:41:56 -0700 (Mon, 09 Jun 2008)

Log Message:
-----------
added to customization guide

Modified Paths:
--------------
    trunk/matplotlib/doc/users/customizing.rst

Modified: trunk/matplotlib/doc/users/customizing.rst
===================================================================
--- trunk/matplotlib/doc/users/customizing.rst	2008-06-09 21:31:46 UTC (rev 5446)
+++ trunk/matplotlib/doc/users/customizing.rst	2008-06-09 21:41:56 UTC (rev 5447)
@@ -1,27 +1,58 @@
 .. _customizing-matplotlib:
 
+**********************
 Customizing matplotlib
-======================
+**********************
 
-matplotlib uses an configuration file ``matplotlibrc`` which is
-located in ``matplotlib/mpl-data/matplotlibrc``.  Every time you
-install matplotlib, this file will be overwritten, so if you want your
-customizations to be saved, please move this file to your ``HOME/.matplotlib``
-directory.
+The matplotlibrc File
+=====================
 
-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.
+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. matplotlib looks for :file:`matplotlibrc` in three
+locations, in the following order:
 
-You can also dynamically change the defaults in a python script or
-interactively from the python shell using the :func:`matplotlib.rc`
-command.  For example to change the default line properties, you could
-do::
+1. :file:`matplotlibrc` in the current working directory, usually used for
+   specific customizations that you do not want to apply elsewhere.
+2. :file:`{HOME}/.matplotlib/matplotlibrc`, for the user's default
+   customizations
+3. :file:`{INSTALL}/matplotlib/mpl-data/matplotlibrc`, where :file:`{INSTALL}`
+   is something like :file:`/usr/lib/python2.5/site-packages` on Linux, and
+   maybe :file:`C:\Python25\Lib\site-packages` on Windows. Every time you
+   install matplotlib, this file will be overwritten, so if you want your
+   customizations to be saved, please move this file to
+   :file:`{HOME}/.matplotlib/matplotlibrc`.
 
-    import matplotlib
-    matplotlib.rc('lines', linewidth=2, color='r')
+See below for a sample :ref:`matplotlibrc file<matplotlibrc-sample>`.
 
+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
+dictionary-like variable called :data:`matplotlib.rcParams`, which is global to
+the matplotlib package. rcParams can be modified directly, for example::
+
+    import matplotlib as mpl
+    mpl.rcParams['lines.linewidth'] = 2
+    mpl.rcParams['lines.color'] = 'r'
+
+Matplotlib also provides a couple of convenience functions for modifying rc
+settings. The :func:`matplotlib.rc` command can be used to modify multiple
+settings in a single group at once, using keyword arguments::
+
+    import matplotlib as mpl
+    mpl.rc('lines', linewidth=2, color='r')
+
+There :func:`matplotlib.rcdefaults` command will restore the standard
+matplotlib default settings.
+
+There is some degree of validation when setting the values of rcParams, see
+:mod:`matplotlib.rcsetup` for details.
+
+
 .. _matplotlibrc-sample:
 
 A sample matplotlibrc file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.