matplotlib · tacaswell · Jul 7, 2018 · Jun 17, 2018
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/pyplot_summary') }}">pyplot</a>|&nbsp;</li>
+        <li><a href="{{ pathto('api/api_overview') }}">API</a>|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">docs</a> &raquo;</li>
 
         {%- for parent in parents %}

diff --git a/doc/api/api_overview.rst b/doc/api/api_overview.rst
@@ -0,0 +1,55 @@
+API Overview
+============
+
+Below we describe several common approaches to plotting with Matplotlib.
+
+.. contents::
+
+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>`
+
+The object-oriented API
+-----------------------
+
+At its core, Matbplotlib 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).
+
+
+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. It's original puropse
+was to mimic a MATLAB-like way of working by importing all functions into the
+global namespace. This is considered bad style nowadays.
diff --git a/doc/api/index.rst b/doc/api/index.rst
@@ -4,17 +4,20 @@
   The Matplotlib API
 ####################
 
-.. only:: html
+.. toctree::
+   :maxdepth: 1
+
+   api_overview.rst
+   api_changes.rst
 
-   :Release: |version|
-   :Date: |today|
+Modules
+=======
 
 .. toctree::
    :maxdepth: 1
 
-   pyplot_summary.rst
-   api_changes.rst
    matplotlib_configuration_api.rst
+   pyplot_summary.rst
    afm_api.rst
    animation_api.rst
    artist_api.rst
@@ -60,22 +63,13 @@
    units_api.rst
    widgets_api.rst
 
-.. currentmodule:: matplotlib
-
-.. autosummary::
-   :toctree: _as_gen
-   :template: autofunctions.rst
-
-   pyplot
-
-
 Toolkits
---------
+========
 
 .. toctree::
    :maxdepth: 1
 
-
+   toolkits/index.rst
    toolkits/mplot3d.rst
    toolkits/axes_grid1.rst
    toolkits/axisartist.rst

diff --git a/doc/api/pyplot_summary.rst b/doc/api/pyplot_summary.rst
@@ -1,33 +1,19 @@
-Below we describe several common approaches to plotting with Matplotlib.
+Pyplot function overview
+------------------------
 
-.. contents::
+.. currentmodule:: matplotlib
 
-The Pyplot API
---------------
+.. autosummary::
+   :toctree: _as_gen
+   :template: autofunctions.rst
+
+   pyplot
 
-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
-:doc:`/tutorials/introductory/pyplot`
-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.
 
 Colors in Matplotlib
 --------------------
@@ -38,4 +24,6 @@ Below we list several ways in which color can be utilized in Matplotlib.
 For a more in-depth look at colormaps, see the
 :doc:`/tutorials/colors/colormaps` tutorial.
 
+.. currentmodule:: matplotlib.pyplot
+
 .. autofunction:: colormaps
diff --git a/doc/contents.rst b/doc/contents.rst
@@ -16,10 +16,9 @@ Overview
 
    users/index.rst
    faq/index.rst
-   api/toolkits/index.rst
+   api/index.rst
    resources/index.rst
    thirdpartypackages/index.rst
-   api/index.rst
    devel/index.rst
    glossary/index.rst
 

diff --git a/doc/users/index.rst b/doc/users/index.rst
@@ -12,11 +12,11 @@ User's Guide
 .. toctree::
     :maxdepth: 2
 
-    history.rst
     installing.rst
     ../tutorials/index.rst
     interactive.rst
     whats_new.rst
+    history.rst
     github_stats.rst
     license.rst
     credits.rst