matplotlib · tacaswell · May 11, 2019 · May 9, 2019 · May 9, 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,54 @@
-.. _api-index:
+API Overview
+============
 
-####################
-  The Matplotlib API
-####################
+Below we describe several common approaches to plotting with Matplotlib.  See
+also the :doc:`api_changes`.
 
 .. toctree::
-   :maxdepth: 1
+   :hidden:
+
+   api_changes
+
+.. contents:: :local:
+
+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_overview.rst
-   api_changes.rst
+.. _api-index:
+
+The object-oriented API
+-----------------------
+
+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).
+
+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)
 
-Modules
-=======
+All Matplotlib submodules are documented here:
 
 .. toctree::
    :maxdepth: 1
@@ -73,8 +109,7 @@ Modules
    units_api.rst
    widgets_api.rst
 
-Toolkits
-========
+... and the ``mpl_toolkits`` here:
 
 .. toctree::
    :maxdepth: 1
@@ -84,3 +119,17 @@ Toolkits
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst
    toolkits/axes_grid.rst
+
+
+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.
+
+`matplotlib.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.