matplotlib · tacaswell · May 11, 2019 · May 11, 2019
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -40,7 +40,7 @@ <h3>{{ _('Navigation') }}</h3>
         <li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
         <li><a href="{{ pathto('gallery/index') }}">examples</a>|&nbsp;</li>
         <li><a href="{{ pathto('tutorials/index') }}">tutorials</a>|&nbsp;</li>
-        <li><a href="{{ pathto('api/api_overview') }}">API</a>|&nbsp;</li>
+        <li><a href="{{ pathto('api/index') }}">API</a>|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">contents</a> &raquo;</li>
 
         {%- for parent in parents %}

diff --git a/doc/api/api_overview.rst b/doc/api/api_overview.rst
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -1,18 +1,74 @@
+API Overview
+============
+
+.. toctree::
+   :hidden:
+
+   api_changes
+
+.. contents:: :local:
+
+See also the :doc:`api_changes`.
+
+Usage patterns
+--------------
+
+Below we describe several common approaches to plotting with Matplotlib.
+
+The pyplot API
+^^^^^^^^^^^^^^
+
+`matplotlib.pyplot` is a collection of command style functions that make
+Matplotlib work like MATLAB. Each pyplot function makes some change to a
+figure: e.g., creates a figure, creates a plotting area in a figure, plots
+some lines in a plotting area, decorates the plot with labels, etc.
+
+`.pyplot` is mainly intended for interactive plots and simple cases of
+programmatic plot generation.
+
+Further reading:
+
+- The `matplotlib.pyplot` function reference
+- :doc:`/tutorials/introductory/pyplot`
+- :ref:`Pyplot examples <pyplots_examples>`
+
 .. _api-index:
 
-####################
-  The Matplotlib API
-####################
+The object-oriented API
+^^^^^^^^^^^^^^^^^^^^^^^
 
-.. toctree::
-   :maxdepth: 1
+At its core, Matplotlib is object-oriented. We recommend directly working
+with the objects, if you need more control and customization of your plots.
+
+In many cases you will create a `.Figure` and one or more
+`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
+on these objects. However, it's also possible to create `.Figure`\ s
+explicitly (e.g. when including them in GUI applications).
 
-   api_overview.rst
-   api_changes.rst
+Further reading:
 
+- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
+  plotting functions.
+- Most of the :ref:`examples <examples-index>` use the object-oriented approach
+  (except for the pyplot section)
+
+The pylab API (disapproved)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+   Since heavily importing into the global namespace may result in unexpected
+   behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
+   instead.
+
+`pylab` is a module that includes `matplotlib.pyplot`, `numpy`
+and some additional functions within a single namespace. Its original purpose
+was to mimic a MATLAB-like way of working by importing all functions into the
+global namespace. This is considered bad style nowadays.
 
 Modules
-=======
+-------
+
+Matplotlib consists of the following submodules:
 
 .. toctree::
    :maxdepth: 1
@@ -73,7 +129,10 @@ Modules
    widgets_api.rst
 
 Toolkits
-========
+--------
+
+:ref:`toolkits-index` are collections of application-specific functions that extend
+Matplotlib. The following toolkits are included:
 
 .. toctree::
    :maxdepth: 1