Include some examples inline in the api docs.

mdboom · mdboom · commit a5fe1a134a2b · 2008-06-26T18:05:17.000Z
svn path=/trunk/matplotlib/; revision=5681
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py
@@ -13,7 +13,7 @@
 source will be included inline, as well as a link to the source.
 """
 
-import sys, os, glob
+import sys, os, glob, shutil
 from docutils.parsers.rst import directives
 
 try:
@@ -40,29 +40,10 @@
            'class': directives.class_option,
            'include-source': directives.flag }
 
-template_no_source = """
+template = """
 .. htmlonly::
 
-   [ `<../%(srcdir)s/%(reference)s>`__,
-    `png <../%(srcdir)s/%(basename)s.hires.png>`__,
-    `pdf <../%(srcdir)s/%(basename)s.pdf>`__]
-
-   .. image:: ../%(srcdir)s/%(basename)s.png
-%(options)s
-
-
-.. latexonly::
-   .. image:: ../%(srcdir)s/%(basename)s.pdf
-%(options)s
-
-"""
-
-template_source = """
-.. literalinclude:: ../pyplots/%(reference)s
-
-.. htmlonly::
-
-   [ `py <../%(srcdir)s/%(reference)s>`__,
+   [`py <../%(srcdir)s/%(basename)s.py>`__,
    `png <../%(srcdir)s/%(basename)s.hires.png>`__,
    `pdf <../%(srcdir)s/%(basename)s.pdf>`__]
 
@@ -90,6 +71,9 @@ def makefig(fullpath, outdir):
     basename, ext = os.path.splitext(fname)
     all_exists = True
 
+    if basedir != outdir:
+        shutil.copyfile(fullpath, os.path.join(outdir, fname))
+
     for format, dpi in formats:
         outname = os.path.join(outdir, '%s.%s' % (basename, format))
         if not os.path.exists(outname):
@@ -109,10 +93,10 @@ def makefig(fullpath, outdir):
         if os.path.exists(outname): continue
         plt.savefig(outname, dpi=dpi)
 
-
 def run(arguments, options, state_machine, lineno):
     reference = directives.uri(arguments[0])
-    basename, ext = os.path.splitext(reference)
+    basedir, fname = os.path.split(reference)
+    basename, ext = os.path.splitext(fname)
 
     # todo - should we be using the _static dir for the outdir, I am
     # not sure we want to corrupt that dir with autogenerated files
@@ -126,16 +110,16 @@ def run(arguments, options, state_machine, lineno):
     # the figs into the right place, so we may want to do that here instead.
 
     if options.has_key('include-source'):
-        template = template_source
+        lines = ['.. literalinclude:: ../pyplots/%(reference)s' % locals()]
         del options['include-source']
     else:
-        template = template_no_source
+        lines = []
+
     options = ['      :%s: %s' % (key, val) for key, val in
                options.items()]
     options = "\n".join(options)
 
-    lines = template % locals()
-    lines = lines.split('\n')
+    lines.extend((template % locals()).split('\n'))
 
     state_machine.insert_input(
         lines, state_machine.input_lines.source(0))
diff --git a/lib/matplotlib/axes.py b/lib/matplotlib/axes.py
@@ -2879,6 +2879,9 @@ def hlines(self, y, xmin, xmax, colors='k', linestyles='solid',
           *linestyle*:
             [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
 
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/hline_demo.py
         """
         if kwargs.get('fmt') is not None:
             raise DeprecationWarning(
@@ -3362,6 +3365,13 @@ def acorr(self, x, **kwargs):
         See the respective :meth:`~matplotlib.axes.Axes.plot` or
         :meth:`~matplotlib.axes.Axes.vlines` functions for
         documentation on valid kwargs.
+
+        **Example:**
+
+        :func:`~matplotlib.pyplot.xcorr` above, and
+        :func:`~matplotlib.pyplot.acorr` below.
+
+        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py
         """
         return self.xcorr(x, x, **kwargs)
     acorr.__doc__ = cbook.dedent(acorr.__doc__) % martist.kwdocd
@@ -3410,6 +3420,13 @@ def xcorr(self, x, y, normed=False, detrend=mlab.detrend_none, usevlines=False,
 
         *maxlags* is a positive integer detailing the number of lags to show.
         The default value of *None* will return all ``(2*len(x)-1)`` lags.
+
+        **Example:**
+
+        :func:`~matplotlib.pyplot.xcorr` above, and
+        :func:`~matplotlib.pyplot.acorr` below.
+
+        .. plot:: ../mpl_examples/pylab_examples/xcorr_demo.py
         """
 
         Nx = len(x)
@@ -3706,6 +3723,12 @@ def bar(self, left, height, width=0.8, bottom=None,
         Other optional kwargs:
 
         %(Rectangle)s
+
+        **Example:**
+
+        A stacked bar chart.
+
+        .. plot:: ../mpl_examples/pylab_examples/bar_stacked.py
         """
         if not self._hold: self.cla()
 
@@ -3998,6 +4021,10 @@ def broken_barh(self, xranges, yrange, **kwargs):
         or a sequence of arguments for the various bars, ie::
 
           facecolors = ('black', 'red', 'green')
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/broken_barh.py
         """
         col = mcoll.BrokenBarHCollection(xranges, yrange, **kwargs)
         self.add_collection(col, autolim=True)
@@ -5013,6 +5040,10 @@ def hexbin(self, x, y, gridsize = 100, bins = None,
         :meth:`~matplotlib.collection.PolyCollection.get_array` on
         this :class:`~matplotlib.collections.PolyCollection` to get
         the counts in each hexagon.
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/hexbin_demo.py
         """
 
         if not self._hold: self.cla()
@@ -5166,6 +5197,10 @@ def arrow(self, x, y, dx, dy, **kwargs):
 
         Optional kwargs control the arrow properties:
         %(FancyArrow)s
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/arrow_demo.py
         """
         a = mpatches.FancyArrow(x, y, dx, dy, **kwargs)
         self.add_artist(a)
@@ -5225,6 +5260,10 @@ def fill(self, *args, **kwargs):
         kwargs control the Polygon properties:
 
         %(Polygon)s
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/fill_demo.py
         """
         if not self._hold: self.cla()
 
@@ -5334,6 +5373,10 @@ def imshow(self, X, cmap=None, norm=None, aspect=None,
         Additional kwargs are :class:`~matplotlib.artist.Artist` properties:
 
         %(Artist)s
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/image_demo.py
         """
 
         if not self._hold: self.cla()
@@ -6081,42 +6124,6 @@ def hist(self, x, bins=10, range=None, normed=False, cumulative=False,
 
         %(Rectangle)s
 
-        Here is an example which generates a histogram of normally
-        distributed random numbers and plot the analytic PDF over it::
-
-            import numpy as np
-            import matplotlib.pyplot as plt
-            import matplotlib.mlab as mlab
-
-            mu, sigma = 100, 15
-            x = mu + sigma * np.random.randn(10000)
-
-            fig = plt.figure()
-            ax = fig.add_subplot(111)
-
-            # the histogram of the data
-            n, bins, patches = ax.hist(x, 50, normed=1, facecolor='green', alpha=0.75)
-
-            # hist uses np.histogram under the hood to create 'n' and 'bins'.
-            # np.histogram returns the bin edges, so there will be 50 probability
-            # density values in n, 51 bin edges in bins and 50 patches.  To get
-            # everything lined up, we'll compute the bin centers
-            bincenters = 0.5*(bins[1:]+bins[:-1])
-
-            # add a 'best fit' line for the normal PDF
-            y = mlab.normpdf( bincenters, mu, sigma)
-            l = ax.plot(bincenters, y, 'r--', linewidth=1)
-
-            ax.set_xlabel('Smarts')
-            ax.set_ylabel('Probability')
-            ax.set_title(r'$\mathrm{Histogram\ of\ IQ:}\ \mu=100,\ \sigma=15$')
-            ax.set_xlim(40, 160)
-            ax.set_ylim(0, 0.03)
-            ax.grid(True)
-
-            #fig.savefig('histogram_demo',dpi=72)
-            plt.show()
-
         You can use labels for your histogram, and only the first
         :class:`~matplotlib.patches.Rectangle` gets the label (the
         others get the magic string '_nolegend_'.  This will make the
@@ -6126,6 +6133,9 @@ def hist(self, x, bins=10, range=None, normed=False, cumulative=False,
             ax.hist(12+3*np.random.randn(1000), label='women', alpha=0.5)
             ax.legend()
 
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/histogram_demo.py
         """
         if not self._hold: self.cla()
 
@@ -6413,6 +6423,10 @@ def csd(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         kwargs control the Line2D properties:
 
         %(Line2D)s
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/csd_demo.py
         """
         if not self._hold: self.cla()
         pxy, freqs = mlab.csd(x, y, NFFT, Fs, detrend, window, noverlap)
@@ -6466,6 +6480,10 @@ def cohere(self, x, y, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
         properties of the coherence plot:
 
         %(Line2D)s
+
+        **Example:**
+
+        .. plot:: ../mpl_examples/pylab_examples/cohere_demo.py
         """
         if not self._hold: self.cla()
         cxy, freqs = mlab.cohere(x, y, NFFT, Fs, detrend, window, noverlap)
