Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit c351e78

Browse filesBrowse files
tacaswelltacaswell
authored
Merge pull request #11451 from timhoffm/pyplot-summary
DOC: Cleanup Matplotlib API docs
2 parents 35083bd + ac7e830 commit c351e78
Copy full SHA for c351e78

File tree

Expand file treeCollapse file tree

6 files changed

+78
-42
lines changed
Filter options
Expand file treeCollapse file tree

6 files changed

+78
-42
lines changed

‎doc/_templates/layout.html

Copy file name to clipboardExpand all lines: doc/_templates/layout.html
+1-1Lines 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

Copy file name to clipboard
+55Lines 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

Copy file name to clipboardExpand all lines: doc/api/index.rst
+10-16Lines 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

Copy file name to clipboard
+10-22Lines 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

Copy file name to clipboardExpand all lines: doc/contents.rst
+1-2Lines 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

Copy file name to clipboardExpand all lines: doc/users/index.rst
+1-1Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.