Add docs for style package

tonysyu · tonysyu · commit f5ecf5e70b99 · 2013-11-17T14:04:47.000-06:00
diff --git a/doc/users/beginner.rst b/doc/users/beginner.rst
@@ -13,6 +13,7 @@ Beginner's Guide
     :maxdepth: 2
 
     pyplot_tutorial.rst
+    style_sheets.rst
     navigation_toolbar.rst
     index_text.rst
     image_tutorial.rst
diff --git a/doc/users/style_sheets.rst b/doc/users/style_sheets.rst
@@ -0,0 +1,90 @@
+.. _style-sheets
+
+***********************************
+Customizing plots with style sheets
+***********************************
+
+
+The ``style`` package adds support for easy-to-switch plotting "styles" with
+the same parameters as a matplotlibrc_ file.
+
+There are a number of pre-defined styles provided by matplotlib. 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::
+
+   >>> from matplotlib import style
+   >>> style.use('ggplot')
+
+To list all available styles, use::
+
+   >>> print style.available
+
+
+Defining your own style
+=======================
+
+You can create custom styles and use them by calling ``style.use`` with the
+path or URL to the style sheet. Alternatively, if you add your
+``<style-name>.mplstyle`` file to ``~/.matplotlib/stylelib`` (you may need to
+create this directory), you can reuse your custom style sheet with a call to
+``style.use(<style-name>)``. Note that a custom style sheet in
+``~/.matplotlib/stylelib`` will override a style sheet defined by matplotlib if
+the styles have the same name.
+
+For example, you might want to create
+``~/.matplotlib/stylelib/presentation.mplstyle`` with the following::
+
+   axes.titlesize : 24
+   axes.labelsize : 20
+   lines.linewidth : 3
+   lines.markersize : 10
+   xtick.labelsize : 16
+   ytick.labelsize : 16
+
+Then, when you want to adapt a plot designed for a paper to one that looks
+good in a presentation, you can just add::
+
+   >>> from matplotlib import style
+   >>> style.use('presentation')
+
+
+Composing styles
+================
+
+Style sheets are designed to be composed together. So you can have a style
+sheet that customizes colors and a separate style sheet that alters element
+sizes for presentations. These styles can easily be combined by passing
+a list of styles::
+
+   >>> from matplotlib import style
+   >>> style.use(['dark_background', 'presentation'])
+
+Note that styles further to the right will overwrite values that are already
+defined by styles on the right.
+
+
+Temporary styling
+=================
+
+If you only want to use a style for a specific block of code but don't want
+to change the global styling, the style package provides a context manager
+for limiting your changes to a specific scope. To isolate the your styling
+changes, you can write something like the following::
+
+
+   >>> import numpy as np
+   >>> import matplotlib.pyplot as plt
+   >>> from matplotlib import style
+   >>>
+   >>> with style.context(('dark_background')):
+   >>>     plt.plot(np.sin(np.linspace(0, 2*np.pi)), 'r-o')
+   >>>
+   >>> # Some plotting code with the default style
+   >>>
+   >>> plt.show()
+
+
+.. _matplotlibrc: http://matplotlib.sourceforge.net/users/customizing.html
+.. _ggplot: http://had.co.nz/ggplot/
+.. _R: http://www.r-project.org/
diff --git a/doc/users/whats_new.rst b/doc/users/whats_new.rst
@@ -98,6 +98,23 @@ an offset will be determined such that the tick labels are
 meaningful. If `False` then the full number will be formatted in all
 conditions.
 
+``style`` package added
+```````````````````````
+You can now easily switch between different styles using the new ``style``
+package::
+
+   >>> from matplotlib import style
+   >>> style.use('dark_background')
+
+Subsequent plots will use updated colors, sizes, etc. To list all available
+styles, use::
+
+   >>> print style.available
+
+You can add your own custom ``<style name>.mplstyle`` files to
+``~/.matplotlib/stylelib`` or call ``use`` with a URL pointing to a file with
+``matplotlibrc`` settings.
+
 .. _whats-new-1-3:
 
 new in matplotlib-1.3
