diff --git a/doc/conf.py b/doc/conf.py index d9712743abfc..e62952541a75 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,7 +28,8 @@ extensions = ['matplotlib.sphinxext.mathmpl', 'sphinxext.math_symbol_table', 'sphinx.ext.autodoc', 'matplotlib.sphinxext.only_directives', 'sphinx.ext.doctest', 'sphinx.ext.autosummary', - 'matplotlib.sphinxext.plot_directive', 'sphinx.ext.inheritance_diagram', + 'matplotlib.sphinxext.plot_directive', + 'sphinx.ext.inheritance_diagram', 'sphinxext.gen_gallery', 'sphinxext.gen_rst', 'matplotlib.sphinxext.ipython_console_highlighting', 'sphinxext.github', @@ -117,6 +118,7 @@ ('text_labels_and_annotations', 'Text, labels, and annotations'), ('ticks_and_spines', 'Ticks and spines'), ('subplots_axes_and_figures', 'Subplots, axes, and figures'), + ('style_sheets', 'Style sheets'), ('specialty_plots', 'Specialty plots'), ('showcase', 'Showcase'), ('api', 'API'), diff --git a/doc/users/beginner.rst b/doc/users/beginner.rst index d1eb6e9deca5..c895415c4ffd 100644 --- 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 new file mode 100644 index 000000000000..563ac542c8ec --- /dev/null +++ b/doc/users/style_sheets.rst @@ -0,0 +1,89 @@ +.. _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:: + + >>> import matplotlib.pyplot as plt + >>> plt.style.use('ggplot') + +To list all available styles, use:: + + >>> print plt.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 +``.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()``. 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:: + + >>> import matplotlib.pyplot as plt + >>> plt.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:: + + >>> import matplotlib.pyplot as plt + >>> plt.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 + >>> + >>> with plt.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 index 5bd6969afecf..886e60c16f0e 100644 --- a/doc/users/whats_new.rst +++ b/doc/users/whats_new.rst @@ -98,6 +98,26 @@ 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 ``