Skip to content

Commit ac7e830

Browse files
timhoffmtimhoffm
committed
Cleanup Matplotlib API docs
1 parent ead2ff8 commit ac7e830

File tree

6 files changed

+78
-42
lines changed

6 files changed

+78
-42
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/pyplot_summary') }}">pyplot</a>|&nbsp;</li>
43+
<li><a href="{{ pathto('api/api_overview') }}">API</a>|&nbsp;</li>
4444
<li><a href="{{ pathto('contents') }}">docs</a> &raquo;</li>
4545

4646
{%- for parent in parents %}

‎doc/api/api_overview.rst‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
API Overview
2+
============
3+
4+
Below we describe several common approaches to plotting with Matplotlib.
5+
6+
.. contents::
7+
8+
The pyplot API
9+
--------------
10+
11+
`matplotlib.pyplot` is a collection of command style functions that make
12+
Matplotlib work like MATLAB. Each pyplot function makes some change to a
13+
figure: e.g., creates a figure, creates a plotting area in a figure, plots
14+
some lines in a plotting area, decorates the plot with labels, etc.
15+
16+
`.pyplot` is mainly intended for interactive plots and simple cases of
17+
programmatic plot generation.
18+
19+
Further reading:
20+
21+
- The `matplotlib.pyplot` function reference
22+
- :doc:`/tutorials/introductory/pyplot`
23+
- :ref:`Pyplot examples <pyplots_examples>`
24+
25+
The object-oriented API
26+
-----------------------
27+
28+
At its core, Matbplotlib is object-oriented. We recommend directly working
29+
with the objects, if you need more control and customization of your plots.
30+
31+
In many cases you will create a `.Figure` and one or more
32+
`~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work
33+
on these objects. However, it's also possible to create `.Figure`\ s
34+
explicitly (e.g. when including them in GUI applications).
35+
36+
Further reading:
37+
38+
- `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of
39+
plotting functions.
40+
- Most of the :ref:`examples <examples-index>` use the object-oriented approach
41+
(except for the pyplot section).
42+
43+
44+
The pylab API (disapproved)
45+
---------------------------
46+
47+
.. warning::
48+
Since heavily importing into the global namespace may result in unexpected
49+
behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot`
50+
instead.
51+
52+
`matplotlib.pylab` is a module that includes `matplotlib.pyplot`, `numpy`
53+
and some additional functions within a single namespace. It's original puropse
54+
was to mimic a MATLAB-like way of working by importing all functions into the
55+
global namespace. This is considered bad style nowadays.

‎doc/api/index.rst‎

Lines changed: 10 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,20 @@
44
The Matplotlib API
55
####################
66

7-
.. only:: html
7+
.. toctree::
8+
:maxdepth: 1
9+
10+
api_overview.rst
11+
api_changes.rst
812

9-
:Release: |version|
10-
:Date: |today|
13+
Modules
14+
=======
1115

1216
.. toctree::
1317
:maxdepth: 1
1418

15-
pyplot_summary.rst
16-
api_changes.rst
1719
matplotlib_configuration_api.rst
20+
pyplot_summary.rst
1821
afm_api.rst
1922
animation_api.rst
2023
artist_api.rst
@@ -60,22 +63,13 @@
6063
units_api.rst
6164
widgets_api.rst
6265

63-
.. currentmodule:: matplotlib
64-
65-
.. autosummary::
66-
:toctree: _as_gen
67-
:template: autofunctions.rst
68-
69-
pyplot
70-
71-
7266
Toolkits
73-
--------
67+
========
7468

7569
.. toctree::
7670
:maxdepth: 1
7771

78-
72+
toolkits/index.rst
7973
toolkits/mplot3d.rst
8074
toolkits/axes_grid1.rst
8175
toolkits/axisartist.rst

‎doc/api/pyplot_summary.rst‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,19 @@
1-
Below we describe several common approaches to plotting with Matplotlib.
1+
Pyplot function overview
2+
------------------------
23

3-
.. contents::
4+
.. currentmodule:: matplotlib
45

5-
The Pyplot API
6-
--------------
6+
.. autosummary::
7+
:toctree: _as_gen
8+
:template: autofunctions.rst
9+
10+
pyplot
711

8-
The :mod:`matplotlib.pyplot` module contains functions that allow you to generate
9-
many kinds of plots quickly. For examples that showcase the use
10-
of the :mod:`matplotlib.pyplot` module, see the
11-
:doc:`/tutorials/introductory/pyplot`
12-
or the :ref:`pyplots_examples`. We also recommend that you look into
13-
the object-oriented approach to plotting, described below.
1412

1513
.. currentmodule:: matplotlib.pyplot
1614

1715
.. autofunction:: plotting
1816

19-
The Object-Oriented API
20-
-----------------------
21-
22-
Most of these functions also exist as methods in the
23-
:class:`matplotlib.axes.Axes` class. You can use them with the
24-
"Object Oriented" approach to Matplotlib.
25-
26-
While it is easy to quickly generate plots with the
27-
:mod:`matplotlib.pyplot` module,
28-
we recommend using the object-oriented approach for more control
29-
and customization of your plots. See the methods in the
30-
:meth:`matplotlib.axes.Axes` class for many of the same plotting functions.
3117

3218
Colors in Matplotlib
3319
--------------------
@@ -38,4 +24,6 @@ Below we list several ways in which color can be utilized in Matplotlib.
3824
For a more in-depth look at colormaps, see the
3925
:doc:`/tutorials/colors/colormaps` tutorial.
4026

27+
.. currentmodule:: matplotlib.pyplot
28+
4129
.. autofunction:: colormaps

‎doc/contents.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,9 @@ Overview
1616

1717
users/index.rst
1818
faq/index.rst
19-
api/toolkits/index.rst
19+
api/index.rst
2020
resources/index.rst
2121
thirdpartypackages/index.rst
22-
api/index.rst
2322
devel/index.rst
2423
glossary/index.rst
2524

‎doc/users/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ User's Guide
1212
.. toctree::
1313
:maxdepth: 2
1414

15-
history.rst
1615
installing.rst
1716
../tutorials/index.rst
1817
interactive.rst
1918
whats_new.rst
19+
history.rst
2020
github_stats.rst
2121
license.rst
2222
credits.rst

0 commit comments

Comments
 (0)