8000 Merge doc/api/api_overview and doc/api/index. · matplotlib/matplotlib@b5ccbff · GitHub
[go: up one dir, main page]
Skip to content

Commit b5ccbff

Browse files
anntzeranntzer
committed
Merge doc/api/api_overview and doc/api/index.
1 parent 959e9f3 commit b5ccbff

File tree

3 files changed

+55
-68
lines changed

3 files changed

+55
-68
lines changed

‎doc/_templates/layout.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ <h3>{{ _('Navigation') }}</h3>
4040
<li><a href="{{ pathto('index') }}">home</a>|&nbsp;</li>
4141
<li><a href="{{ pathto('gallery/index') }}">examples</a>|&nbsp;</li>
4242
<li><a href="{{ pathto('tutorials/index') }}">tutorials</a>|&nbsp;</li>
43-
<li><a href="{{ pathto('api/api_overview') }}">API</a>|&nbsp;</li>
43+
<li><a href="{{ pathto('api/index') }}">API</a>|&nbsp;</li>
4444
<li><a href="{{ pathto('contents') }}">contents</a> &raquo;</li>
4545

4646
{%- for parent in parents %}

‎doc/api/api_overview.rst

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎doc/api/index.rst

Lines changed: 54 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,47 @@
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

7-
.. toctree::
8-
:maxdepth: 1
7+
.. contents:: :local:
8+
9+
The pyplot API
10+
--------------
11+
12+
`matplotlib.pyplot` is a collection of command style functions that make
13+
Matplotlib work like MATLAB. Each pyplot function makes some change to a
14+
figure: e.g., creates a figure, creates a plotting area in a figure, plots
15+
some lines in a plotting area, decorates the plot with labels, etc.
16+
17+
`.pyplot` is mainly intended for interactive plots and simple cases of
18+
programmatic plot generation.
19+
20+
Further reading:
21+
22+
- The `matplotlib.pyplot` function reference
23+
- :doc:`/tutorials/introductory/pyplot`
24+
- :ref:`Pyplot examples <pyplots_examples>`
925

10-
api_overview.rst
11-
api_changes.rst
26+
The object-oriented API
27+
-----------------------
1228

29+
At its core, Matplotlib is object-oriented. We recommend directly working
30+
with the objects, if you need more control and customization of your plots.
1331

14-
Modules
15-
=======
32+
In many cases you will create a `.Figure` and one or more
33+
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
34+
on these objects. However, it's also possible to create `.Figure`\ s
35+
explicitly (e.g. when including them in GUI applications).
36+
37+
Further reading:
38+
39+
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
40+
plotting functions.
41+
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
42+
(except for the pyplot section)
43+
44+
All Matplotlib submodules are documented here:
1645

1746
.. toctree::
1847
:maxdepth: 1
@@ -73,8 +102,7 @@ Modules
73102
units_api.rst
74103
widgets_api.rst
75104

76-
Toolkits
77-
========
105+
... and the ``mpl_toolkits`` here:
78106

79107
.. toctree::
80108
:maxdepth: 1
@@ -84,3 +112,17 @@ Toolkits
84112
toolkits/axes_grid1.rst
85113
toolkits/axisartist.rst
86114
toolkits/axes_grid.rst
115+
116+
117+
The pylab API (disapproved)
118+
---------------------------
119+
120+
.. warning::
121+
Since heavily importing into the global namespace may result in unexpected
122+
behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
123+
instead.
124+
125+
`matplotlib.pylab` is a module that includes `matplotlib.pyplot`, `numpy`
126+
and some additional functions within a single namespace. Its original purpose
127+
was to mimic a MATLAB-like way of working by importing all functions into the
128+
global namespace. This is considered bad style nowadays.

0 commit comments

Comments
 (0)
0