From: <md...@us...> - 2008-10-17 19:32:23
|
Revision: 6251 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=6251&view=rev Author: mdboom Date: 2008-10-17 19:32:16 +0000 (Fri, 17 Oct 2008) Log Message: ----------- 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. Modified Paths: -------------- trunk/matplotlib/doc/contents.rst trunk/matplotlib/doc/devel/documenting_mpl.rst trunk/matplotlib/doc/examples/gen_rst.py trunk/matplotlib/doc/faq/howto_faq.rst trunk/matplotlib/doc/pyplots/boxplot_demo.py trunk/matplotlib/doc/pyplots/tex_demo.hires.png trunk/matplotlib/doc/pyplots/tex_demo.pdf trunk/matplotlib/doc/pyplots/tex_demo.png trunk/matplotlib/doc/pyplots/tex_demo.py trunk/matplotlib/doc/pyplots/tex_unicode_demo.hires.png trunk/matplotlib/doc/pyplots/tex_unicode_demo.pdf trunk/matplotlib/doc/pyplots/tex_unicode_demo.png trunk/matplotlib/doc/sphinxext/plot_directive.py trunk/matplotlib/doc/users/annotations.rst trunk/matplotlib/doc/users/artists.rst trunk/matplotlib/doc/users/mathtext.rst trunk/matplotlib/doc/users/pyplot_tutorial.rst trunk/matplotlib/doc/users/screenshots.rst trunk/matplotlib/doc/users/text_intro.rst trunk/matplotlib/doc/users/text_props.rst trunk/matplotlib/doc/users/usetex.rst trunk/matplotlib/examples/api/agg_oo.py trunk/matplotlib/examples/api/font_family_rc.py trunk/matplotlib/examples/api/font_file.py trunk/matplotlib/examples/pylab_examples/annotation_demo.py trunk/matplotlib/examples/pylab_examples/barh_demo.py trunk/matplotlib/examples/pylab_examples/colours.py trunk/matplotlib/examples/pylab_examples/cursor_demo.py trunk/matplotlib/examples/pylab_examples/dannys_example.py trunk/matplotlib/examples/pylab_examples/dashtick.py trunk/matplotlib/examples/pylab_examples/font_table_ttf.py trunk/matplotlib/examples/pylab_examples/ginput_demo.py trunk/matplotlib/examples/pylab_examples/ginput_manual_clabel.py trunk/matplotlib/examples/pylab_examples/movie_demo.py trunk/matplotlib/examples/pylab_examples/print_stdout.py trunk/matplotlib/examples/pylab_examples/pstest.py trunk/matplotlib/examples/pylab_examples/scatter_profile.py trunk/matplotlib/examples/pylab_examples/shared_axis_across_figures.py trunk/matplotlib/examples/pylab_examples/simple_plot_fps.py trunk/matplotlib/examples/pylab_examples/system_monitor.py trunk/matplotlib/examples/pylab_examples/tex_unicode_demo.py trunk/matplotlib/examples/pylab_examples/unicode_demo.py trunk/matplotlib/examples/pylab_examples/webapp_demo.py trunk/matplotlib/lib/matplotlib/artist.py trunk/matplotlib/lib/matplotlib/axes.py trunk/matplotlib/lib/matplotlib/contour.py trunk/matplotlib/lib/matplotlib/figure.py trunk/matplotlib/lib/matplotlib/text.py trunk/matplotlib/lib/matplotlib/transforms.py Removed Paths: ------------- trunk/matplotlib/doc/pyplots/contour_demo.py trunk/matplotlib/doc/pyplots/errorbar_demo.py trunk/matplotlib/doc/pyplots/tex_unicode_demo.py trunk/matplotlib/examples/pylab_examples/auto_layout.py Modified: trunk/matplotlib/doc/contents.rst =================================================================== --- trunk/matplotlib/doc/contents.rst 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/contents.rst 2008-10-17 19:32:16 UTC (rev 6251) @@ -20,9 +20,8 @@ api/index.rst glossary/index.rst - .. htmlonly:: - examples/index.rst + - `Examples <examples/index.html>`_ * :ref:`genindex` * :ref:`modindex` Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst =================================================================== --- trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/devel/documenting_mpl.rst 2008-10-17 19:32:16 UTC (rev 6251) @@ -208,47 +208,38 @@ Dynamically generated figures ----------------------------- -The top level :file:`doc` dir has a folder called :file:`pyplots` in -which you should include any pyplot plotting scripts that you want to -generate figures for the documentation. It is not necessary to -explicitly save the figure in the script, this will be done -automatically at build time to insure that the code that is included -runs and produces the advertised figure. Several figures will be -saved with the same basnename as the filename when the documentation -is generated (low and high res PNGs, a PDF). Matplotlib includes a -Sphinx extension (:file:`sphinxext/plot_directive.py`) for generating -the images from the python script and including either a png copy for -html or a pdf for latex:: +Figures can be automatically generated from scripts and included in +the docs. It is not necessary to explicitly save the figure in the +script, this will be done automatically at build time to ensure that +the code that is included runs and produces the advertised figure. +Several figures will be saved with the same basename as the filename +when the documentation is generated (low and high res PNGs, a PDF). +Matplotlib includes a Sphinx extension +(:file:`sphinxext/plot_directive.py`) for generating the images from +the python script and including either a png copy for html or a pdf +for latex:: - .. plot:: pyplot_simple.py + .. plot:: pyplots/pyplot_simple.py :include-source: +If the script produces multiple figures (through multiple calls to +:func:`pyplot.figure`), each will be given a numbered file name and +included. + +The path should be relative to the ``doc`` directory. Any plots +specific to the documentation should be added to the ``doc/pyplots`` +directory and committed to SVN. Plots from the ``examples`` directory +may be referenced through the symlink ``mpl_examples`` in the ``doc`` +directory. eg.:: + + .. plot:: mpl_examples/pylab_examples/simple_plot.py + The ``:scale:`` directive rescales the image to some percentage of the original size, though we don't recommend using this in most cases since it is probably better to choose the correct figure size and dpi in mpl and let it handle the scaling. ``:include-source:`` will present the contents of the file, marked up as source code. -You can also point to local files with relative path. Use the -sym-link for mpl_examples in case we do a reorganization of the doc -directory at some point, eg:: - - .. plot:: ../mpl_examples/pylab_examples/simple_plot.py - -If the example file needs to access data, it is easy to get screwed up -with relative paths since the python example may be run from a diffent -location in the plot directive build framework. To work around this, -you can add your example data to mpl-data/example and refer to it in -the example file like so:: - - import matplotlib - # datafile is a file object - datafile = matplotlib.get_example_data('goog.npy') - r = np.load(datafile).view(np.recarray) - -Try to keep the example datafiles relatively few and relatively small -to control the size of the binaries we ship. - Static figures -------------- @@ -261,10 +252,20 @@ requirements necessary to generate a new figure. Once these steps have been taken, these figures can be included in the usual way:: - .. plot:: tex_unicode_demo.py + .. plot:: pyplots/tex_unicode_demo.py :include-source +Examples +-------- +The source of the files in the ``examples`` directory are +automatically included in the HTML docs. An image is generated and +included for all examples in the ``api`` and ``pylab_examples`` +directories. To exclude the example from having an image rendered, +insert the following special comment anywhere in the script:: + + # -*- noplot -*- + .. _referring-to-mpl-docs: Referring to mpl documents Modified: trunk/matplotlib/doc/examples/gen_rst.py =================================================================== --- trunk/matplotlib/doc/examples/gen_rst.py 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/examples/gen_rst.py 2008-10-17 19:32:16 UTC (rev 6251) @@ -5,12 +5,22 @@ import matplotlib.cbook as cbook - import os +import re import sys fileList = [] rootdir = '../mpl_examples' +def out_of_date(original, derived): + """ + Returns True if derivative is out-of-date wrt original, + both of which are full file paths. + """ + return (not os.path.exists(derived) or + os.stat(derived).st_mtime < os.stat(original).st_mtime) + +noplot_regex = re.compile(r"#\s*-\*-\s*noplot\s*-\*-") + datad = {} for root, subFolders, files in os.walk(rootdir): for fname in files: @@ -22,7 +32,7 @@ contents = file(fullpath).read() # indent relpath = os.path.split(root)[-1] - datad.setdefault(relpath, []).append((fname, contents)) + datad.setdefault(relpath, []).append((fullpath, fname, contents)) subdirs = datad.keys() subdirs.sort() @@ -48,7 +58,7 @@ for subdir in subdirs: if not os.path.exists(subdir): os.makedirs(subdir) - + static_dir = os.path.join('..', '_static', 'examples') if not os.path.exists(static_dir): os.makedirs(static_dir) @@ -83,37 +93,48 @@ print subdir - + data = datad[subdir] data.sort() - for fname, contents in data: + for fullname, fname, contents in data: + static_file = os.path.join(static_dir, fname) + basename, ext = os.path.splitext(fname) + rstfile = '%s.rst'%basename + outfile = os.path.join(subdir, rstfile) + fhsubdirIndex.write(' %s\n'%rstfile) - static_file = os.path.join(static_dir, fname) + if (not out_of_date(fullname, static_file) and + not out_of_date(fullname, outfile)): + continue + + print ' %s'%fname + fhstatic = file(static_file, 'w') fhstatic.write(contents) fhstatic.close() - basename, ext = os.path.splitext(fname) - rstfile = '%s.rst'%basename - outfile = os.path.join(subdir, rstfile) - fhsubdirIndex.write(' %s\n'%rstfile) fh = file(outfile, 'w') fh.write('.. _%s-%s:\n\n'%(subdir, basename)) title = '%s example code: %s'%(subdir, fname) fh.write(title + '\n') fh.write('='*len(title) + '\n\n') - - print ' %s'%fname + do_plot = (subdir in ('api', + 'pylab_examples', + 'units') and + not noplot_regex.search(contents)) - linkname = os.path.join('..', '..', '_static', 'examples', subdir, fname) - fh.write('%s (`link to source <%s>`_)::\n\n'%(fname, linkname)) + if do_plot: + fh.write("\n\n.. plot:: %s\n\n::\n\n" % fullname[3:]) + else: + linkname = os.path.join('..', '..', '_static', 'examples', subdir, fname) + fh.write("[`source code <%s>`_]\n\n::\n\n" % linkname) # indent the contents contents = '\n'.join([' %s'%row.rstrip() for row in contents.split('\n')]) + fh.write(contents) - fh.write(contents) fh.write('\n\nKeyword: codex (see :ref:`how-to-search-examples`)') fh.close() Modified: trunk/matplotlib/doc/faq/howto_faq.rst =================================================================== --- trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/faq/howto_faq.rst 2008-10-17 19:32:16 UTC (rev 6251) @@ -148,7 +148,7 @@ of each of the labels and uses it to move the left of the subplots over so that the tick labels fit in the figure -.. plot:: auto_subplots_adjust.py +.. plot:: pyplots/auto_subplots_adjust.py :include-source: .. _howto-ticks: @@ -191,7 +191,7 @@ below shows the default behavior in the left subplots, and the manual setting in the right subplots. -.. plot:: align_ylabels.py +.. plot:: pyplots/align_ylabels.py :include-source: .. _date-index-plots: Modified: trunk/matplotlib/doc/pyplots/boxplot_demo.py =================================================================== --- trunk/matplotlib/doc/pyplots/boxplot_demo.py 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/pyplots/boxplot_demo.py 2008-10-17 19:32:16 UTC (rev 6251) @@ -1,21 +1,55 @@ -import numpy as np -import matplotlib.pyplot as plt +#!/usr/bin/python -spread = np.random.rand(50) * 100 -center = np.ones(25) * 50 -flier_high = np.random.rand(10) * 100 + 100 -flier_low = np.random.rand(10) * -100 -data = np.concatenate((spread, center, flier_high, flier_low), 0) +# +# Example boxplot code +# +from pylab import * + +# fake up some data +spread= rand(50) * 100 +center = ones(25) * 50 +flier_high = rand(10) * 100 + 100 +flier_low = rand(10) * -100 +data =concatenate((spread, center, flier_high, flier_low), 0) + +# basic plot +boxplot(data) +#savefig('box1') + +# notched plot +figure() +boxplot(data,1) +#savefig('box2') + +# change outlier point symbols +figure() +boxplot(data,0,'gD') +#savefig('box3') + +# don't show outlier points +figure() +boxplot(data,0,'') +#savefig('box4') + +# horizontal boxes +figure() +boxplot(data,0,'rs',0) +#savefig('box5') + +# change whisker length +figure() +boxplot(data,0,'rs',0,0.75) +#savefig('box6') + # fake up some more data -spread = np.random.rand(50) * 100 -center = np.ones(25) * 40 -flier_high = np.random.rand(10) * 100 + 100 -flier_low = np.random.rand(10) * -100 -d2 = np.concatenate( (spread, center, flier_high, flier_low), 0 ) +spread= rand(50) * 100 +center = ones(25) * 40 +flier_high = rand(10) * 100 + 100 +flier_low = rand(10) * -100 +d2 = concatenate( (spread, center, flier_high, flier_low), 0 ) data.shape = (-1, 1) d2.shape = (-1, 1) - #data = concatenate( (data, d2), 1 ) # Making a 2-D array only works if all the columns are the # same length. If they are not, then use a list instead. @@ -23,7 +57,9 @@ # a 2-D array into a list of vectors internally anyway. data = [data, d2, d2[::2,0]] # multiple box plots on one figure +figure() +boxplot(data) +#savefig('box7') -plt.boxplot(data) -plt.show() +show() Deleted: trunk/matplotlib/doc/pyplots/contour_demo.py =================================================================== --- trunk/matplotlib/doc/pyplots/contour_demo.py 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/pyplots/contour_demo.py 2008-10-17 19:32:16 UTC (rev 6251) @@ -1,66 +0,0 @@ -#!/usr/bin/env python -""" -Illustrate simple contour plotting, contours on an image with -a colorbar for the contours, and labelled contours. - -See also contour_image.py. -""" -import matplotlib -import numpy as np -import matplotlib.cm as cm -import matplotlib.mlab as mlab -import matplotlib.pyplot as plt - -matplotlib.rcParams['xtick.direction'] = 'out' -matplotlib.rcParams['ytick.direction'] = 'out' - -delta = 0.025 -x = np.arange(-3.0, 3.0, delta) -y = np.arange(-2.0, 2.0, delta) -X, Y = np.meshgrid(x, y) -Z1 = mlab.bivariate_normal(X, Y, 1.0, 1.0, 0.0, 0.0) -Z2 = mlab.bivariate_normal(X, Y, 1.5, 0.5, 1, 1) -# difference of Gaussians -Z = 10.0 * (Z2 - Z1) - - -# You can use a colormap to specify the colors; the default -# colormap will be used for the contour lines -plt.figure() -im = plt.imshow(Z, interpolation='bilinear', origin='lower', - cmap=cm.gray, extent=(-3,3,-2,2)) -levels = np.arange(-1.2, 1.6, 0.2) -CS = plt.contour(Z, levels, - origin='lower', - linewidths=2, - extent=(-3,3,-2,2)) - -#Thicken the zero contour. -zc = CS.collections[6] -plt.setp(zc, linewidth=4) - -plt.clabel(CS, levels[1::2], # label every second level - inline=1, - fmt='%1.1f', - fontsize=14) - -# make a colorbar for the contour lines -CB = plt.colorbar(CS, shrink=0.8, extend='both') - -plt.title('Lines with colorbar') -#plt.hot() # Now change the colormap for the contour lines and colorbar -plt.flag() - -# We can still add a colorbar for the image, too. -CBI = plt.colorbar(im, orientation='horizontal', shrink=0.8) - -# This makes the original colorbar look a bit out of place, -# so let's improve its position. - -l,b,w,h = plt.gca().get_position().bounds -ll,bb,ww,hh = CB.ax.get_position().bounds -CB.ax.set_position([ll, b+0.1*h, ww, h*0.8]) - - -#savefig('contour_demo') -plt.show() Deleted: trunk/matplotlib/doc/pyplots/errorbar_demo.py =================================================================== --- trunk/matplotlib/doc/pyplots/errorbar_demo.py 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/pyplots/errorbar_demo.py 2008-10-17 19:32:16 UTC (rev 6251) @@ -1,8 +0,0 @@ -import numpy as np -import matplotlib.pyplot as plt - -t = np.arange(0.1, 4, 0.1) -s = np.exp(-t) -e, f = 0.1*np.absolute(np.random.randn(2, len(s))) -plt.errorbar(t, s, e, fmt='o') # vertical symmetric -plt.show() Modified: trunk/matplotlib/doc/pyplots/tex_demo.hires.png =================================================================== (Binary files differ) Modified: trunk/matplotlib/doc/pyplots/tex_demo.pdf =================================================================== --- trunk/matplotlib/doc/pyplots/tex_demo.pdf 2008-10-17 18:51:10 UTC (rev 6250) +++ trunk/matplotlib/doc/pyplots/tex_demo.pdf 2008-10-17 19:32:16 UTC (rev 6251) @@ -4,7 +4,7 @@ << /Type /Catalog /Pages 3 0 R >> endobj 2 0 obj -<< /CreationDate (D:20081014161405-05'00') +<< /CreationDate (D:20081017151352-04'00') /Producer (matplotlib pdf backend) /Creator (matplotlib 0.98.3, http://matplotlib.sf.net) >> endobj @@ -44,673 +44,291 @@ 1864 endobj 36 0 obj -<< /BaseFont /CMMI12 /Type /Font /Subtype /Type1 /FontDescriptor 35 0 R +<< +/Encoding << +/Differences [ 0 /minus /periodcentered /multiply /asteriskmath /divide /diamondmath +/plusminus /minusplus /circleplus /circleminus /circlemultiply +/circledivide /circledot /circlecopyrt /openbullet /bullet /equivasymptotic +/equivalence /reflexsubset /reflexsuperset /lessequal /greaterequal +/precedesequal /followsequal /similar /approxequal /propersubset +/propersuperset /lessmuch /greatermuch /precedes /follows /arrowleft +/arrowright /arrowup /arrowdown /arrowboth /arrownortheast /arrowsoutheast +/similarequal /arrowdblleft /arrowdblright /arrowdblup /arrowdbldown +/arrowdblboth /arrownorthwest /arrowsouthwest /proportional /prime +/infinity /element /owner /triangle /triangleinv /negationslash /mapsto +/universal /existential /logicalnot /emptyset /Rfractur /Ifractur +/latticetop /perpendicular /aleph /A /B /C /D /E /F /G /H /I /J /K /L /M /N +/O /P /Q /R /S /T /U /V /W /X /Y /Z /union /intersection /unionmulti +/logicaland /logicalor /turnstileleft /turnstileright /floorleft +/floorright /ceilingleft /ceilingright /braceleft /braceright +/angbracketleft /angbracketright /bar /bardbl /arrowbothv /arrowdblbothv +/backslash /wreathproduct /radical /coproduct /nabla /integral /unionsq +/intersectionsq /subsetsqequal /supersetsqequal /section /dagger /daggerdbl +/paragraph /club /diamond /heart /spade /arrowleft /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /minus +/periodcentered /multiply /asteriskmath /divide /diamondmath /plusminus +/minusplus /circleplus /circleminus /.notdef /.notdef /circlemultiply +/circledivide /circledot /circlecopyrt /openbullet /bullet /equivasymptotic +/equivalence /reflexsubset /reflexsuperset /lessequal /greaterequal +/precedesequal /followsequal /similar /approxequal /propersubset +/propersuperset /lessmuch /greatermuch /precedes /follows /arrowleft /spade +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef /.notdef +/.notdef /.notdef /.notdef ] +/Type /Encoding >> +/BaseFont /CMSY10 /Type /Font /Subtype /Type1 /FontDescriptor 35 0 R /Widths 34 0 R /LastChar 125 /FirstChar 0 >> endobj 34 0 obj -[ 606 815 748 679 728 811 765 571 652 598 757 622 552 507 433 395 427 483 -456 346 563 571 589 483 427 555 505 556 425 527 579 613 636 609 458 577 808 -505 354 641 979 979 979 979 271 271 489 489 489 489 489 489 489 489 489 489 -489 489 271 271 761 489 761 489 516 734 743 700 812 724 633 772 811 431 541 -833 666 947 784 748 631 775 745 602 573 665 570 924 812 568 670 380 380 380 -979 979 410 513 416 421 508 453 482 468 563 334 405 509 291 856 584 470 491 -434 441 461 353 557 473 699 556 477 454 312 377 623 ] +[ 777 277 777 500 777 500 777 777 777 777 777 777 777 1000 500 500 777 777 +777 777 777 777 777 777 777 777 777 777 1000 1000 777 777 1000 1000 500 500 +1000 1000 1000 777 1000 1000 611 611 1000 1000 1000 777 274 1000 666 666 +888 888 0 0 555 555 666 500 722 722 777 777 611 798 656 526 771 527 718 594 +844 544 677 761 689 1200 820 796 695 816 847 605 544 625 612 987 713 668 +724 666 666 666 666 666 611 611 444 444 444 444 500 500 388 388 277 500 500 +611 500 277 833 750 833 416 666 666 777 777 444 444 444 611 777 777 ] endobj 35 0 obj -<< /FontFile 37 0 R /FontName /CMMI12 /Descent -250 -/FontBBox [ -30 -250 1026 750 ] /CapHeight 1000 /Ascent 750 +<< /FontFile 37 0 R /FontName /CMSY10 /Descent -960 +/FontBBox [ -29 -960 1116 775 ] /CapHeight 1000 /Ascent 775 /FontFamily (Computer Modern) /StemV 50 /Flags 68 /XHeight 500 /ItalicAngle -14 /Type /FontDescriptor >> endobj 37 0 obj -<< /Length3 0 /Length2 27245 /Length1 3667 /Length 28908 +<< /Length3 0 /Length2 21763 /Length1 4313 /Length 23626 /Filter /FlateDecode >> stream -x\x9C\x94\xB7eX˺\xB5\x8D\xBBC\x90`3@pwww - \xD8\xC4\xDD\xDD=\xB7\xE0Np\xF7\xE0\xC1\xDD\x82{p\xF8f\xF6\xD9\xEF Y\xEB\xFC\xF9.\xFE0Fu\xEB\xA9\xD1\xF5t\xBF\xA7\xA8B'ddc |