diff --git a/doc/api/axes_api.rst b/doc/api/axes_api.rst index 3457368fa51c..e637263a39bf 100644 --- a/doc/api/axes_api.rst +++ b/doc/api/axes_api.rst @@ -1,3 +1,5 @@ +.. _matplotlib-axes: + ******************* ``matplotlib.axes`` ******************* diff --git a/doc/api/index.rst b/doc/api/index.rst index 644842ee70ae..11d367715535 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -36,35 +36,60 @@ methods on them to plot data, add axis labels and a figure title. Usage patterns -------------- -Below we describe several common approaches to plotting with Matplotlib. See -:ref:`api_interfaces` for an explanation of the trade-offs between the supported user -APIs. +Matplotlib provides two different interfaces: +- Within the *Axes interface* you create a Figure and one or more Axes objects + (typically using `.pyplot.subplots`). Then, you use methods on these objects to add + data, configure limits, set labels etc. +- The *pyplot interface* consists of functions that make changes -The explicit API -^^^^^^^^^^^^^^^^ +See :ref:`api_interfaces` for a more detailed description of both and their recommended +use cases. -At its core, Matplotlib is an object-oriented library. We recommend directly -working with the objects if you need more control and customization of your -plots. +.. grid:: 2 -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). + .. grid-item-card:: ``Axes`` interface -Further reading: + API: + + - `~matplotlib.figure.Figure`: configure all figure related settings + - :ref:`Axes `: add data, configure limits, set labels etc. + + Examples: + + - Most of the :ref:`examples ` use this + (except for the pyplot section) + + .. grid-item-card:: ``pyplot`` interface + + API: + + - `matplotlib.pyplot` function reference + + Examples: + + - :ref:`pyplot_tutorial` + - :ref:`Pyplot examples ` + + +The Axes interface +^^^^^^^^^^^^^^^^^^ + +Typically, you will use `.pyplot.subplots` to create a `.Figure` and one or more +`~matplotlib.axes.Axes` objects. From then on, you will use methods on these objects +to add data, configure limits, set labels etc. + +Relevant API: + + +Examples: -- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of - plotting functions. -- Most of the :ref:`examples ` use the object-oriented approach - (except for the pyplot section) -The implicit API -^^^^^^^^^^^^^^^^ +The pyplot interface +^^^^^^^^^^^^^^^^^^^^ -`matplotlib.pyplot` is a collection of functions that make +`matplotlib.pyplot` is function based interface.a collection of 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. @@ -74,9 +99,6 @@ programmatic plot generation. Further reading: -- The `matplotlib.pyplot` function reference -- :ref:`pyplot_tutorial` -- :ref:`Pyplot examples ` .. _api-index: