matplotlib · QuLogic · May 12, 2017 · May 6, 2017 · May 7, 2017 · May 7, 2017
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
@@ -55,18 +55,18 @@ <h1>Introduction</h1>
   interface toolkits.</p>
 
   <div class="responsive_screenshots">
-    <a a href="{{ pathto('users/screenshots') }}">
+    <a a href="{{ pathto('tutorials/01_introductory/sample_plots') }}">
       <div class="responsive_subfig">
-        <img align="middle", src="{{ pathto('_static/membrane_frontpage.png', 1) }}", border="0", alt="screenshots"/>
+        <img align="middle", src="{{ pathto('_images/sphx_glr_membrane_thumb.png', 1) }}", border="0", alt="screenshots"/>
       </div>
       <div class="responsive_subfig">
-        <img align="middle", src="{{ pathto('_static/histogram_frontpage.png', 1) }}", border="0", alt="screenshots"/>
+        <img align="middle", src="{{ pathto('_images/sphx_glr_histogram_thumb1.png', 1) }}", border="0", alt="screenshots"/>
       </div>
       <div class="responsive_subfig">
-        <img align="middle", src="{{ pathto('_static/contour_frontpage.png', 1) }}", border="0", alt="screenshots"/>
+        <img align="middle", src="{{ pathto('_images/sphx_glr_contour_thumb.png', 1) }}", border="0", alt="screenshots"/>
       </div>
       <div class="responsive_subfig">
-        <img align="middle", src="{{ pathto('_static/surface3d_frontpage.png', 1) }}", border="0", alt="screenshots"/>
+        <img align="middle", src="{{ pathto('_images/sphx_glr_3D_thumb.png', 1) }}", border="0", alt="screenshots"/>
       </div>
     </a>
   </div>
@@ -75,8 +75,8 @@ <h1>Introduction</h1>
   <p>Matplotlib tries to make easy things easy and hard things possible.
   You can generate plots, histograms, power spectra, bar charts,
   errorcharts, scatterplots, etc., with just a few lines of code.
-  For a example, see the <a href="{{ pathto('users/screenshots')
-  }}">screenshots</a> and <a href="{{ pathto('gallery/index') }}">thumbnail</a> gallery.</p>
+  For examples, see the <a href="{{ pathto('tutorials/01_introductory/sample_plots')
+  }}">sample plots</a> and <a href="{{ pathto('gallery/index') }}">thumbnail</a> gallery.</p>
 
 <p>For simple plotting the <tt>pyplot</tt> module provides a
   MATLAB-like interface, particularly when combined

diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -1,8 +1,43 @@
-Plotting commands summary
-=========================
+Below we describe several common approaches to plotting with Matplotlib.
+
+.. contents::
+
+The Pyplot API
+--------------
+
+The :mod:`matplotlib.pyplot` module contains functions that allow you to generate
+many kinds of plots quickly. For examples that showcase the use
+of the :mod:`matplotlib.pyplot` module, see the
+:ref:`sphx_glr_tutorials_01_introductory_pyplot.py`
+or the :ref:`pyplots_examples`. We also recommend that you look into
+the object-oriented approach to plotting, described below.
 
 .. currentmodule:: matplotlib.pyplot
 
 .. autofunction:: plotting
 
+The Object-Oriented API
+-----------------------
+
+Most of these functions also exist as methods in the
+:class:`matplotlib.axes.Axes` class. You can use them with the
+"Object Oriented" approach to Matplotlib.
+
+While it is easy to quickly generate plots with the
+:mod:`matplotlib.pyplot` module,
+we recommend using the object-oriented approach for more control
+and customization of your plots. See the methods in the
+:meth:`matplotlib.axes.Axes` class for many of the same plotting functions.
+For examples of the OO approach to Matplotlib, see the
+:ref:`API Examples<api_examples>`.
+
+Colors in Matplotlib
+--------------------
+
+There are many colormaps you can use to map data onto color values.
+Below we list several ways in which color can be utilized in Matplotlib.
+
+For a more in-depth look at colormaps, see the
+:ref:`sphx_glr_tutorials_colors_colormaps.py` tutorial.
+
 .. autofunction:: colormaps
diff --git a/doc/contents.rst b/doc/contents.rst
@@ -15,11 +15,11 @@ Overview
    :maxdepth: 2
 
    users/index.rst
-   api/index.rst
    faq/index.rst
    mpl_toolkits/index.rst
    resources/index.rst
    thirdpartypackages/index.rst
+   api/index.rst
    devel/index.rst
    glossary/index.rst
 

diff --git a/doc/make.py b/doc/make.py
@@ -52,45 +52,6 @@ def linkcheck():
         [sys.executable]
         + '-msphinx -b linkcheck -d build/doctrees . build/linkcheck'.split())
 
-
-# For generating PNGs of the top row of index.html:
-FRONTPAGE_PY_PATH = "../examples/frontpage/"  # python scripts location
-FRONTPAGE_PNG_PATH = "_static/"  # png files location
-# png files and corresponding generation scripts:
-FRONTPAGE_PNGS = {"surface3d_frontpage.png": "3D.py",
-                  "contour_frontpage.png":   "contour.py",
-                  "histogram_frontpage.png": "histogram.py",
-                  "membrane_frontpage.png":  "membrane.py"}
-
-
-def generate_frontpage_pngs(only_if_needed=True):
-    """Executes the scripts for PNG generation of the top row of index.html.
-
-    If `only_if_needed` is `True`, then the PNG file is only generated, if it
-    doesn't exist or if the python file is newer.
-
-    Note that the element `div.responsive_screenshots` in the file
-    `_static/mpl.css` has the height and cumulative width of the used PNG files
-    as attributes. This ensures that the magnification of those PNGs is <= 1.
-    """
-    for fn_png, fn_py in FRONTPAGE_PNGS.items():
-        pn_png = os.path.join(FRONTPAGE_PNG_PATH, fn_png)  # get full paths
-        pn_py = os.path.join(FRONTPAGE_PY_PATH, fn_py)
-
-        # Read file modification times:
-        mtime_py = os.path.getmtime(pn_py)
-        mtime_png = (os.path.getmtime(pn_png) if os.path.exists(pn_png) else
-                     mtime_py - 1)  # set older time, if file doesn't exist
-
-        if only_if_needed and mtime_py <= mtime_png:
-            continue  # do nothing if png is newer
-
-        # Execute python as subprocess (preferred over os.system()):
-        subprocess.check_call(
-            [sys.executable, pn_py])  # raises CalledProcessError()
-        os.rename(fn_png, pn_png)  # move file to _static/ directory
-
-
 DEPSY_PATH = "_static/depsy_badge.svg"
 DEPSY_URL = "http://depsy.org/api/package/pypi/matplotlib/badge.svg"
 DEPSY_DEFAULT = "_static/depsy_badge_default.svg"
@@ -121,7 +82,6 @@ def fetch_depsy_badge():
 def html(buildername='html'):
     """Build Sphinx 'html' target. """
     check_build()
-    generate_frontpage_pngs()
     fetch_depsy_badge()
 
     rc = '../lib/matplotlib/mpl-data/matplotlibrc'
@@ -213,10 +173,6 @@ def clean():
         for filename in glob.glob(pattern):
             if os.path.exists(filename):
                 os.remove(filename)
-        for fn in FRONTPAGE_PNGS.keys():  # remove generated PNGs
-            pn = os.path.join(FRONTPAGE_PNG_PATH, fn)
-            if os.path.exists(pn):
-                os.remove(os.path.join(pn))
 
 
 def build_all():

diff --git a/doc/users/examples_index.rst b/doc/users/examples_index.rst
diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -15,7 +15,6 @@ User's Guide
     intro.rst
     installing.rst
     interactive.rst
-    examples_index
     whats_new.rst
     github_stats.rst
     license.rst

diff --git a/examples/lines_bars_and_markers/categorical_variables.py b/examples/lines_bars_and_markers/categorical_variables.py
@@ -0,0 +1,37 @@
+"""
+==============================
+Plotting categorical variables
+==============================
+
+How to use categorical variables in Matplotlib.
+
+Many times you want to create a plot that uses categorical variables
+in Matplotlib. Matplotlib allows you to pass categorical variables directly to
+many plotting functions, which we demonstrate below.
+"""
+import matplotlib.pyplot as plt
+
+data = {'apples': 10, 'oranges': 15, 'lemons': 5, 'limes': 20}
+names = list(data.keys())
+values = list(data.values())
+
+fig, axs = plt.subplots(1, 3, figsize=(9, 3), sharey=True)
+axs[0].bar(names, values)
+axs[1].scatter(names, values)
+axs[2].plot(names, values)
+fig.suptitle('Categorical Plotting')
+
+
+###############################################################################
+# This works on both axes:
+
+cat = ["bored", "happy", "bored", "bored", "happy", "bored"]
+dog = ["happy", "happy", "happy", "happy", "bored", "bored"]
+activity = ["combing", "drinking", "feeding", "napping", "playing", "washing"]
+
+fig, ax = plt.subplots()
+ax.plot(activity, dog, label="dog")
+ax.plot(activity, cat, label="cat")
+ax.legend()
+
+plt.show()
diff --git a/tutorials/01_introductory/pyplot.py b/tutorials/01_introductory/pyplot.py
@@ -118,6 +118,30 @@
 plt.ylabel('entry b')
 plt.show()
 
+###############################################################################
+# .. _plotting-with-categorical-vars:
+#
+# Plotting with categorical variables
+# ===================================
+#
+# It is also possible to create a plot using categorical variables.
+# Matplotlib allows you to pass categorical variables directly to
+# many plotting functions. For example:
+
+names = ['group_a', 'group_b', 'group_c']
+values = [1, 10, 100]
+
+plt.figure(1, figsize=(9, 3))
+
+plt.subplot(131)
+plt.bar(names, values)
+plt.subplot(132)
+plt.scatter(names, values)
+plt.subplot(133)
+plt.plot(names, values)
+plt.suptitle('Categorical Plotting')
+plt.show()
+
 ###############################################################################
 # .. _controlling-line-properties:
 #