1- .. _api-index :
1+ API Overview
2+ ============
23
3- ####################
4- The Matplotlib API
5- ####################
4+ Below we describe several common approaches to plotting with Matplotlib. See
5+ also the :doc: `api_changes `.
66
77.. toctree ::
8- :maxdepth: 1
8+ :hidden:
9+
10+ api_changes
11+
12+ .. contents :: :local:
13+
14+ The pyplot API
15+ --------------
16+
17+ `matplotlib.pyplot ` is a collection of command style functions that make
18+ Matplotlib work like MATLAB. Each pyplot function makes some change to a
19+ figure: e.g., creates a figure, creates a plotting area in a figure, plots
20+ some lines in a plotting area, decorates the plot with labels, etc.
21+
22+ `.pyplot ` is mainly intended for interactive plots and simple cases of
23+ programmatic plot generation.
24+
25+ Further reading:
26+
27+ - The `matplotlib.pyplot ` function reference
28+ - :doc: `/tutorials/introductory/pyplot `
29+ - :ref: `Pyplot examples <pyplots_examples >`
930
10- api_overview.rst
11- api_changes.rst
31+ .. _api-index :
32+
33+ The object-oriented API
34+ -----------------------
35+
36+ At its core, Matplotlib is object-oriented. We recommend directly working
37+ with the objects, if you need more control and customization of your plots.
38+
39+ In many cases you will create a `.Figure ` and one or more
40+ `~matplotlib.axes.Axes ` using `.pyplot.subplots ` and from then on only work
41+ on these objects. However, it's also possible to create `.Figure `\ s
42+ explicitly (e.g. when including them in GUI applications).
43+
44+ Further reading:
1245
46+ - `matplotlib.axes.Axes ` and `matplotlib.figure.Figure ` for an overview of
47+ plotting functions.
48+ - Most of the :ref: `examples <examples-index >` use the object-oriented approach
49+ (except for the pyplot section)
1350
14- Modules
15- =======
51+ All Matplotlib submodules are documented here:
1652
1753.. toctree ::
1854 :maxdepth: 1
@@ -73,8 +109,7 @@ Modules
73109 units_api.rst
74110 widgets_api.rst
75111
76- Toolkits
77- ========
112+ ... and the ``mpl_toolkits `` here:
78113
79114.. toctree ::
80115 :maxdepth: 1
@@ -84,3 +119,17 @@ Toolkits
84119 toolkits/axes_grid1.rst
85120 toolkits/axisartist.rst
86121 toolkits/axes_grid.rst
122+
123+
124+ The pylab API (disapproved)
125+ ---------------------------
126+
127+ .. warning ::
128+ Since heavily importing into the global namespace may result in unexpected
129+ behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot `
130+ instead.
131+
132+ `matplotlib.pylab ` is a module that includes `matplotlib.pyplot `, `numpy `
133+ and some additional functions within a single namespace. Its original purpose
134+ was to mimic a MATLAB-like way of working by importing all functions into the
135+ global namespace. This is considered bad style nowadays.
0 commit comments