DOC: Add links to explicit vs implicit API everywhere "OO" is used

Closes matplotlib#18249

Author: tacaswell

doc/api/index.rst

@@ -114,10 +114,33 @@ Alphabetical list of modules:
 Usage patterns
 --------------
 
-Below we describe several common approaches to plotting with Matplotlib.
+Below we describe several common approaches to plotting with Matplotlib.  See
+:ref:`api_interfaces` for an explanation of the trade off of the supported user
+APIs.
 
-The pyplot API
-^^^^^^^^^^^^^^
+
+The Explicit API
+^^^^^^^^^^^^^^^^
+
+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.
+
+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 implicit API
+^^^^^^^^^^^^^^^^
 
 `matplotlib.pyplot` is a collection of functions that make
 Matplotlib work like MATLAB. Each pyplot function makes some change to a
@@ -135,24 +158,6 @@ Further reading:
 
 .. _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)
-
 The pylab API (discouraged)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/users/project/history.rst

@@ -11,7 +11,7 @@ History
 Matplotlib is a library for making 2D plots of arrays in `Python
 <https://www.python.org>`_.  Although it has its origins in emulating
 the MATLAB graphics commands, it is
-independent of MATLAB, and can be used in a Pythonic, object oriented
+independent of MATLAB, and can be used in a Pythonic, object-oriented
 way.  Although Matplotlib is written primarily in pure Python, it
 makes heavy use of `NumPy <https://numpy.org>`_ and other extension
 code to provide good performance even for large arrays.

examples/misc/pythonic_matplotlib.py

@@ -3,9 +3,9 @@
 Pythonic Matplotlib
 ===================
 
-Some people prefer to write more pythonic, object-oriented code
-rather than use the pyplot interface to matplotlib.  This example shows
-you how.
+Some people prefer to write more "Pythonic", explicitly object-oriented code
+rather than use the implicit pyplot interface to Matplotlib.  This example
+shows you how.
 
 Unless you are an application developer, I recommend using part of the
 pyplot interface, particularly the figure, close, subplot, axes, and
@@ -14,7 +14,7 @@
 instances, managing the bounding boxes of the figure elements,
 creating and realizing GUI windows and embedding figures in them.
 
-If you are an application developer and want to embed matplotlib in
+If you are an application developer and want to embed Matplotlib in
 your application, follow the lead of examples/embedding_in_wx.py,
 examples/embedding_in_gtk.py or examples/embedding_in_tk.py.  In this
 case you will want to control the creation of all your figures,
@@ -28,7 +28,7 @@
 application developers, however.
 
 If you see an example in the examples dir written in pyplot interface,
-and you want to emulate that using the true python method calls, there
+and you want to emulate that using the true Python method calls, there
 is an easy mapping.  Many of those examples use 'set' to control
 figure properties.  Here's how to map those commands onto instance
 methods
@@ -52,6 +52,7 @@
     a.set_yticklabels([])
     a.set_xticks([])
     a.set_yticks([])
+
 """
 
 import matplotlib.pyplot as plt

examples/subplots_axes_and_figures/multiple_figs_demo.py

@@ -10,10 +10,11 @@
 
 .. note::
 
-    We discourage working with multiple figures in pyplot because managing
-    the *current figure* is cumbersome and error-prone. Instead, we recommend
-    to use the object-oriented approach and call methods on Figure and Axes
-    instances.
+    We discourage working with multiple figures in implicit pyplot interface
+    because managing the *current figure* is cumbersome and
+    error-prone. Instead, we recommend to use the explicit approach and call
+    methods on Figure and Axes instances. See :ref:`api_interfaces` for an
+    explanation of the tradeoffs between the implicit and explicit interfaces.
 
 """
 import matplotlib.pyplot as plt

lib/matplotlib/__init__.py

@@ -17,10 +17,12 @@
 
 at the ipython shell prompt.
 
-For the most part, direct use of the object-oriented library is encouraged when
-programming; pyplot is primarily for working interactively.  The exceptions are
-the pyplot functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`,
-and `.pyplot.savefig`, which can greatly simplify scripting.
+For the most part, direct use of the explicit object-oriented library is
+encouraged when programming; the implicit pyplot interface is primarily for
+working interactively.  The exceptions are the pyplot functions
+`.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and `.pyplot.savefig`,
+which can greatly simplify scripting.  See :ref:`api_interfaces` for an
+explanation of the tradeoffs between the implicit and explicit interfaces.
 
 Modules include:
 
@@ -79,6 +81,7 @@
 
 Occasionally the internal documentation (python docstrings) will refer
 to MATLAB®, a registered trademark of The MathWorks, Inc.
+
 """
 
 import atexit

lib/matplotlib/pyplot.py

@@ -16,7 +16,7 @@
     y = np.sin(x)
     plt.plot(x, y)
 
-The explicit (object-oriented) API is recommended for complex plots, though
+The explicit object-oriented API is recommended for complex plots, though
 pyplot is still usually used to create the figure and often the axes in the
 figure. See `.pyplot.figure`, `.pyplot.subplots`, and
 `.pyplot.subplot_mosaic` to create figures, and
@@ -29,6 +29,10 @@
     y = np.sin(x)
     fig, ax = plt.subplots()
     ax.plot(x, y)
+
+
+See :ref:`api_interfaces` for an explanation of the tradeoffs between the
+implicit and explicit interfaces.
 """
 
 import functools

tutorials/introductory/images.py

@@ -37,15 +37,15 @@
 cells below those that create the plot will change the plot - it is a
 live object in memory.
 
-This tutorial will use Matplotlib's imperative-style plotting
-interface, pyplot.  This interface maintains global state, and is very
-useful for quickly and easily experimenting with various plot
-settings.  The alternative is the object-oriented interface, which is also
-very powerful, and generally more suitable for large application
-development.  If you'd like to learn about the object-oriented
-interface, a great place to start is our :doc:`Quick start guide
-</tutorials/introductory/quick_start>`.  For now, let's get on
-with the imperative-style approach:
+This tutorial will use Matplotlib's implicit plotting interface, pyplot.  This
+interface maintains global state, and is very useful for quickly and easily
+experimenting with various plot settings.  The alternative is the explicit,
+which is more suitable for large application development.  For an explanation
+of the tradeoffs between the implicit and explicit interfaces See
+:ref:`api_interfaces` and the :doc:`Quick start guide
+</tutorials/introductory/quick_start>` to start using the explicit interface.
+For now, let's get on with the implicit approach:
+
 """
 
 import matplotlib.pyplot as plt

tutorials/introductory/lifecycle.py

@@ -17,15 +17,17 @@
     <https://pbpython.com/effective-matplotlib.html>`_
     by Chris Moffitt. It was transformed into this tutorial by Chris Holdgraf.
 
-A note on the Object-Oriented API vs. Pyplot
-============================================
+A note on the explicit vs. implicit interfaces
+==============================================
 
-Matplotlib has two interfaces. The first is an object-oriented (OO)
-interface. In this case, we utilize an instance of :class:`axes.Axes`
-in order to render visualizations on an instance of :class:`figure.Figure`.
+Matplotlib has two interfaces. For an explanation of the tradeoffs between the
+implicit and explicit interfaces see :ref:`api_interfaces`.
 
-The second is based on MATLAB and uses a state-based interface. This is
-encapsulated in the :mod:`.pyplot` module. See the :doc:`pyplot tutorials
+The first is an explicit object-oriented (OO) interface. In this case, we
+utilize an instance of :class:`axes.Axes` in order to render visualizations on
+an instance of :class:`figure.Figure`.  The second is based on MATLAB and uses
+an implicit global state-based interface.  This is encapsulated in the
+:mod:`.pyplot` module. See the :doc:`pyplot tutorials
 </tutorials/introductory/pyplot>` for a more in-depth look at the pyplot
 interface.
 
@@ -41,14 +43,15 @@
 
 .. note::
 
-   In general, try to use the object-oriented interface over the pyplot
-   interface.
+   In general, try to use the explicit interface over the implicit pyplot
+   interface for plotting.
 
 Our data
 ========
 
 We'll use the data from the post from which this tutorial was derived.
 It contains sales information for a number of companies.
+
 """
 
 # sphinx_gallery_thumbnail_number = 10

tutorials/introductory/pyplot.py

@@ -4,19 +4,20 @@
 ===============
 
 An introduction to the pyplot interface.  Please also see
-:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib works.
+:doc:`/tutorials/introductory/quick_start` for an overview of how Matplotlib
+works and :ref:`api_interfaces` for an explanation of the trade off of the
+supported user APIs.
+
 """
 
 ###############################################################################
 # Intro to pyplot
 # ===============
 #
-# :mod:`matplotlib.pyplot` is 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.
+# :mod:`matplotlib.pyplot` is 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.
 #
 # In :mod:`matplotlib.pyplot` various states are preserved
 # across function calls, so that it keeps track of things like
@@ -28,10 +29,11 @@
 #
 # .. note::
 #
-#    the pyplot API is generally less-flexible than the object-oriented API.
-#    Most of the function calls you see here can also be called as methods
-#    from an ``Axes`` object. We recommend browsing the tutorials and
-#    examples to see how this works.
+#    the implicit pyplot API is generally terser but less-flexible than the
+#    explicit API.  Most of the function calls you see here can also be called
+#    as methods from an ``Axes`` object. We recommend browsing the tutorials
+#    and examples to see how this works. See :ref:`api_interfaces` for an
+#    explanation of the trade off of the supported user APIs.
 #
 # Generating visualizations with pyplot is very quick:
 
@@ -301,7 +303,7 @@ def f(t):
 # and the current axes with `~.pyplot.cla`.  If you find
 # it annoying that states (specifically the current image, figure and axes)
 # are being maintained for you behind the scenes, don't despair: this is just a thin
-# stateful wrapper around an object oriented API, which you can use
+# stateful wrapper around an object-oriented API, which you can use
 # instead (see :doc:`/tutorials/intermediate/artists`)
 #
 # If you are making lots of figures, you need to be aware of one

tutorials/introductory/quick_start.py

@@ -134,16 +134,19 @@
 # Coding styles
 # =============
 #
-# The object-oriented and the pyplot interfaces
-# ---------------------------------------------
+# The explicit and the implicit interfaces
+# ----------------------------------------
 #
 # As noted above, there are essentially two ways to use Matplotlib:
 #
 # - Explicitly create Figures and Axes, and call methods on them (the
 #   "object-oriented (OO) style").
-# - Rely on pyplot to automatically create and manage the Figures and Axes, and
+# - Rely on pyplot to implicitly create and manage the Figures and Axes, and
 #   use pyplot functions for plotting.
 #
+# See :ref:`api_interfaces` for an explanation of the tradeoffs between the
+# implicit and explicit interfaces.
+#
 # So one can use the OO-style
 
 x = np.linspace(0, 2, 100)  # Sample data.