adding pyplot API context

choldgraf · choldgraf · commit edf2cf8af69d · 2017-05-07T09:52:25.000-07:00
diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -1,6 +1,27 @@
 Plotting commands summary
 =========================
 
+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`.
+
+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
+so-called "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. For some examples of the OO approach
+to Matplotlib, see the :ref:`api_examples` examples.
+
+The Pyplot API
+--------------
+
 .. currentmodule:: matplotlib.pyplot
 
 .. autofunction:: plotting
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
 
