8000 Backport PR #14176: Merge doc/api/api_overview and doc/api/index. · matplotlib/matplotlib@2573f37 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2573f37

Browse files
tacaswellMeeseeksDev[bot]
tacaswell
authored and
MeeseeksDev[bot]
committed
Backport PR #14176: Merge doc/api/api_overview and doc/api/index.
1 parent a06e364 commit 2573f37

File tree

3 files changed

+69
-65
lines changed

3 files changed

+69
-65
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: 68 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,74 @@
1+
API Overview
2+
============
3+
4+
.. toctree::
5+
:hidden:
6+
7+
api_changes
8+
9+
.. contents:: :local:
10+
11+
See also the :doc:`api_changes`.
12+
13+
Usage patterns
14+
--------------
15+
16+
Below we describe several common approaches to plotting with Matplotlib.
17+
18+
The pyplot API
19+
^^^^^^^^^^^^^^
20+
21+
`matplotlib.pyplot` is a collection of command style functions that make
22+
Matplotlib work like MATLAB. Each pyplot function makes some change to a
23+
figure: e.g., creates a figure, creates a plotting area in a figure, plots
24+
some lines in a plotting area, decorates the plot with labels, etc.
25+
26+
`.pyplot` is mainly intended for interactive plots and simple cases of
27+
programmatic plot generation.
28+
29+
Further reading:
30+
31+
- The `matplotlib.pyplot` function reference
32+
- :doc:`/tutorials/introductory/pyplot`
33+
- :ref:`Pyplot examples <pyplots_examples>`
34+
135
.. _api-index:
236

3-
####################
4-
The Matplotlib API
5-
####################
37+
The object-oriented API
38+
^^^^^^^^^^^^^^^^^^^^^^^
639

7-
.. toctree::
8-
:maxdepth: 1
40+
At its core, Matplotlib is object-oriented. We recommend directly working
41+
with the objects, if you need more control and customization of your plots.
42+
43+
In many cases you will create a `.Figure` and one or more
44+
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
45+
on these objects. However, it's also possible to create `.Figure`\ s
46+
explicitly (e.g. when including them in GUI applications).
947

10-
api_overview.rst
11-
api_changes.rst
48+
Further reading:
1249

50+
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
51+
plotting functions.
52+
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
53+
(except for the pyplot section)
54+
55+
The pylab API (disapproved)
56+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
57+
58+
.. warning::
59+
Since heavily importing into the global namespace may result in unexpected
60+
behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
61+
instead.
62+
63+
`pylab` is a module that includes `matplotlib.pyplot`, `numpy`
64+
and some additional functions within a single namespace. Its original purpose
65+
was to mimic a MATLAB-like way of working by importing all functions into the
66+
global namespace. This is considered bad st AA12 yle nowadays.
1367

1468
Modules
15-
=======
69+
-------
70+
71+
Matplotlib consists of the following submodules:
1672

1773
.. toctree::
1874
:maxdepth: 1
@@ -73,7 +129,10 @@ Modules
73129
widgets_api.rst
74130

75131
Toolkits
76-
========
132+
--------
133+
134+
:ref:`toolkits-index` are collections of application-specific functions that extend
135+
Matplotlib. The following toolkits are included:
77136

78137
.. toctree::
79138
:maxdepth: 1

0 commit comments

Comments
 (0)
0