Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 37c9c3d

Browse files
mdboommdboom
committed
Include output images in examples in documentation.
Add "-*- noplot -*-" markers to examples where we don't want that. The "plot" documentation directive now takes a path relative to the doc/ directory, not doc/pyplots. svn path=/trunk/matplotlib/; revision=6251
1 parent 3710f69 commit 37c9c3d

53 files changed

Lines changed: 355 additions & 316 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎doc/contents.rst‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,8 @@ Overview
2020
api/index.rst
2121
glossary/index.rst
2222

23-
2423
.. htmlonly::
25-
examples/index.rst
24+
- `Examples <examples/index.html>`_
2625

2726
* :ref:`genindex`
2827
* :ref:`modindex`

‎doc/devel/documenting_mpl.rst‎

Lines changed: 35 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -208,47 +208,38 @@ Figures
208208
Dynamically generated figures
209209
-----------------------------
210210

211-
The top level :file:`doc` dir has a folder called :file:`pyplots` in
212-
which you should include any pyplot plotting scripts that you want to
213-
generate figures for the documentation. It is not necessary to
214-
explicitly save the figure in the script, this will be done
215-
automatically at build time to insure that the code that is included
216-
runs and produces the advertised figure. Several figures will be
217-
saved with the same basnename as the filename when the documentation
218-
is generated (low and high res PNGs, a PDF). Matplotlib includes a
219-
Sphinx extension (:file:`sphinxext/plot_directive.py`) for generating
220-
the images from the python script and including either a png copy for
221-
html or a pdf for latex::
222-
223-
.. plot:: pyplot_simple.py
211+
Figures can be automatically generated from scripts and included in
212+
the docs. It is not necessary to explicitly save the figure in the
213+
script, this will be done automatically at build time to ensure that
214+
the code that is included runs and produces the advertised figure.
215+
Several figures will be saved with the same basename as the filename
216+
when the documentation is generated (low and high res PNGs, a PDF).
217+
Matplotlib includes a Sphinx extension
218+
(:file:`sphinxext/plot_directive.py`) for generating the images from
219+
the python script and including either a png copy for html or a pdf
220+
for latex::
221+
222+
.. plot:: pyplots/pyplot_simple.py
224223
:include-source:
225224

225+
If the script produces multiple figures (through multiple calls to
226+
:func:`pyplot.figure`), each will be given a numbered file name and
227+
included.
228+
229+
The path should be relative to the ``doc`` directory. Any plots
230+
specific to the documentation should be added to the ``doc/pyplots``
231+
directory and committed to SVN. Plots from the ``examples`` directory
232+
may be referenced through the symlink ``mpl_examples`` in the ``doc``
233+
directory. eg.::
234+
235+
.. plot:: mpl_examples/pylab_examples/simple_plot.py
236+
226237
The ``:scale:`` directive rescales the image to some percentage of the
227238
original size, though we don't recommend using this in most cases
228239
since it is probably better to choose the correct figure size and dpi
229240
in mpl and let it handle the scaling. ``:include-source:`` will
230241
present the contents of the file, marked up as source code.
231242

232-
You can also point to local files with relative path. Use the
233-
sym-link for mpl_examples in case we do a reorganization of the doc
234-
directory at some point, eg::
235-
236-
.. plot:: ../mpl_examples/pylab_examples/simple_plot.py
237-
238-
If the example file needs to access data, it is easy to get screwed up
239-
with relative paths since the python example may be run from a diffent
240-
location in the plot directive build framework. To work around this,
241-
you can add your example data to mpl-data/example and refer to it in
242-
the example file like so::
243-
244-
import matplotlib
245-
# datafile is a file object
246-
datafile = matplotlib.get_example_data('goog.npy')
247-
r = np.load(datafile).view(np.recarray)
248-
249-
Try to keep the example datafiles relatively few and relatively small
250-
to control the size of the binaries we ship.
251-
252243
Static figures
253244
--------------
254245

@@ -261,9 +252,19 @@ svn. Please also add a line to the README in doc/pyplots for any additional
261252
requirements necessary to generate a new figure. Once these steps have been
262253
taken, these figures can be included in the usual way::
263254

264-
.. plot:: tex_unicode_demo.py
255+
.. plot:: pyplots/tex_unicode_demo.py
265256
:include-source
266257

258+
Examples
259+
--------
260+
261+
The source of the files in the ``examples`` directory are
262+
automatically included in the HTML docs. An image is generated and
263+
included for all examples in the ``api`` and ``pylab_examples``
264+
directories. To exclude the example from having an image rendered,
265+
insert the following special comment anywhere in the script::
266+
267+
# -*- noplot -*-
267268

268269
.. _referring-to-mpl-docs:
269270

‎doc/examples/gen_rst.py‎

Lines changed: 36 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,22 @@
55

66
import matplotlib.cbook as cbook
77

8-
98
import os
9+
import re
1010
import sys
1111
fileList = []
1212
rootdir = '../mpl_examples'
1313

14+
def out_of_date(original, derived):
15+
"""
16+
Returns True if derivative is out-of-date wrt original,
17+
both of which are full file paths.
18+
"""
19+
return (not os.path.exists(derived) or
20+
os.stat(derived).st_mtime < os.stat(original).st_mtime)
21+
22+
noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-")
23+
1424
datad = {}
1525
for root, subFolders, files in os.walk(rootdir):
1626
for fname in files:
@@ -22,7 +32,7 @@
2232
contents = file(fullpath).read()
2333
# indent
2434
relpath = os.path.split(root)[-1]
25-
datad.setdefault(relpath, []).append((fname, contents))
35+
datad.setdefault(relpath, []).append((fullpath, fname, contents))
2636

2737
subdirs = datad.keys()
2838
subdirs.sort()
@@ -48,7 +58,7 @@
4858
for subdir in subdirs:
4959
if not os.path.exists(subdir):
5060
os.makedirs(subdir)
51-
61+
5262
static_dir = os.path.join('..', '_static', 'examples')
5363
if not os.path.exists(static_dir):
5464
os.makedirs(static_dir)
@@ -83,37 +93,48 @@
8393

8494
print subdir
8595

86-
96+
8797
data = datad[subdir]
8898
data.sort()
89-
for fname, contents in data:
90-
99+
for fullname, fname, contents in data:
91100
static_file = os.path.join(static_dir, fname)
92-
fhstatic = file(static_file, 'w')
93-
fhstatic.write(contents)
94-
fhstatic.close()
95-
96101
basename, ext = os.path.splitext(fname)
97102
rstfile = '%s.rst'%basename
98103
outfile = os.path.join(subdir, rstfile)
99104
fhsubdirIndex.write(' %s\n'%rstfile)
105+
106+
if (not out_of_date(fullname, static_file) and
107+
not out_of_date(fullname, outfile)):
108+
continue
109+
110+
print ' %s'%fname
111+
112+
fhstatic = file(static_file, 'w')
113+
fhstatic.write(contents)
114+
fhstatic.close()
115+
100116
fh = file(outfile, 'w')
101117
fh.write('.. _%s-%s:\n\n'%(subdir, basename))
102118
title = '%s example code: %s'%(subdir, fname)
103119

104120
fh.write(title + '\n')
105121
fh.write('='*len(title) + '\n\n')
106-
107122

108-
print ' %s'%fname
123+
do_plot = (subdir in ('api',
124+
'pylab_examples',
125+
'units') and
126+
not noplot_regex.search(contents))
109127

110-
linkname = os.path.join('..', '..', '_static', 'examples', subdir, fname)
111-
fh.write('%s (`link to source <%s>`_)::\n\n'%(fname, linkname))
128+
if do_plot:
129+
fh.write("\n\n.. plot:: %s\n\n::\n\n" % fullname[3:])
130+
else:
131+
linkname = os.path.join('..', '..', '_static', 'examples', subdir, fname)
132+
fh.write("[`source code <%s>`_]\n\n::\n\n" % linkname)
112133

113134
# indent the contents
114135
contents = '\n'.join([' %s'%row.rstrip() for row in contents.split('\n')])
115-
116136
fh.write(contents)
137+
117138
fh.write('\n\nKeyword: codex (see :ref:`how-to-search-examples`)')
118139
fh.close()
119140

‎doc/faq/howto_faq.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ Here is that gets a bounding box in relative figure coordinates (0..1)
148148
of each of the labels and uses it to move the left of the subplots
149149
over so that the tick labels fit in the figure
150150

151-
.. plot:: auto_subplots_adjust.py
151+
.. plot:: pyplots/auto_subplots_adjust.py
152152
:include-source:
153153

154154
.. _howto-ticks:
@@ -191,7 +191,7 @@ behavior by specifying the coordinates of the label. The example
191191
below shows the default behavior in the left subplots, and the manual
192192
setting in the right subplots.
193193

194-
.. plot:: align_ylabels.py
194+
.. plot:: pyplots/align_ylabels.py
195195
:include-source:
196196

197197
.. _date-index-plots:

‎doc/pyplots/boxplot_demo.py‎

Lines changed: 51 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,65 @@
1-
import numpy as np
2-
import matplotlib.pyplot as plt
1+
#!/usr/bin/python
32

4-
spread = np.random.rand(50) * 100
5-
center = np.ones(25) * 50
6-
flier_high = np.random.rand(10) * 100 + 100
7-
flier_low = np.random.rand(10) * -100
8-
data = np.concatenate((spread, center, flier_high, flier_low), 0)
3+
#
4+
# Example boxplot code
5+
#
6+
7+
from pylab import *
8+
9+
# fake up some data
10+
spread= rand(50) * 100
11+
center = ones(25) * 50
12+
flier_high = rand(10) * 100 + 100
13+
flier_low = rand(10) * -100
14+
data =concatenate((spread, center, flier_high, flier_low), 0)
15+
16+
# basic plot
17+
boxplot(data)
18+
#savefig('box1')
19+
20+
# notched plot
21+
figure()
22+
boxplot(data,1)
23+
#savefig('box2')
24+
25+
# change outlier point symbols
26+
figure()
27+
boxplot(data,0,'gD')
28+
#savefig('box3')
29+
30+
# don't show outlier points
31+
figure()
32+
boxplot(data,0,'')
33+
#savefig('box4')
34+
35+
# horizontal boxes
36+
figure()
37+
boxplot(data,0,'rs',0)
38+
#savefig('box5')
39+
40+
# change whisker length
41+
figure()
42+
boxplot(data,0,'rs',0,0.75)
43+
#savefig('box6')
944

1045
# fake up some more data
11-
spread = np.random.rand(50) * 100
12-
center = np.ones(25) * 40
13-
flier_high = np.random.rand(10) * 100 + 100
14-
flier_low = np.random.rand(10) * -100
15-
d2 = np.concatenate( (spread, center, flier_high, flier_low), 0 )
46+
spread= rand(50) * 100
47+
center = ones(25) * 40
48+
flier_high = rand(10) * 100 + 100
49+
flier_low = rand(10) * -100
50+
d2 = concatenate( (spread, center, flier_high, flier_low), 0 )
1651
data.shape = (-1, 1)
1752
d2.shape = (-1, 1)
18-
1953
#data = concatenate( (data, d2), 1 )
2054
# Making a 2-D array only works if all the columns are the
2155
# same length. If they are not, then use a list instead.
2256
# This is actually more efficient because boxplot converts
2357
# a 2-D array into a list of vectors internally anyway.
2458
data = [data, d2, d2[::2,0]]
2559
# multiple box plots on one figure
60+
figure()
61+
boxplot(data)
62+
#savefig('box7')
2663

27-
plt.boxplot(data)
28-
plt.show()
64+
show()
2965

‎doc/pyplots/contour_demo.py‎

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

‎doc/pyplots/errorbar_demo.py‎

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

‎doc/pyplots/tex_demo.hires.png‎

16.8 KB
Loading

‎doc/pyplots/tex_demo.pdf‎

9.98 KB
Binary file not shown.

‎doc/pyplots/tex_demo.png‎

7.14 KB
Loading

0 commit comments

Comments
 (0)