Add "include-source" option.

mdboom · mdboom · commit 6e4593eb6d76 · 2008-06-13T14:40:39.000Z
svn path=/trunk/matplotlib/; revision=5505
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py
@@ -3,10 +3,14 @@
 Given a path to a .py file, it includes the source code inline, then:
 
 - On HTML, will include a .png with a link to a high-res .png.
-  Underneath that, a [source] link will go to a plain text .py of
-  the source.
 
 - On LaTeX, will include a .pdf
+
+This directive supports all of the options of the `image` directive,
+except for `target` (since plot will add its own target).
+
+Additionally, if the :include-source: option is provided, the literal
+source will be included inline, as well as a link to the source.
 """
 
 from docutils.parsers.rst import directives
@@ -25,9 +29,23 @@
            'width': directives.length_or_percentage_or_unitless,
            'scale': directives.nonnegative_int,
            'align': align,
-           'class': directives.class_option}
+           'class': directives.class_option,
+           'include-source': directives.flag }
+
+template_no_source = """
+.. htmlonly::
+
+   .. image:: %(reference)s.png
+      :target: %(reference)s.hires.png
+%(options)s
+
+.. latexonly::
+   .. image:: %(reference)s.pdf
+%(options)s
+
+"""
 
-template = """
+template_source = """
 .. literalinclude:: %(reference)s.py
 
 .. htmlonly::
@@ -36,7 +54,7 @@
       :target: %(reference)s.hires.png
 %(options)s
 
-   `[original %(basename)s.py] <%(reference)s.py>`_
+   `[%(basename)s.py] <%(reference)s.py>`_
 
 .. latexonly::
    .. image:: %(reference)s.pdf
@@ -46,8 +64,16 @@
 
 def run(arguments, options, state_machine, lineno):
     reference = directives.uri(arguments[0])
-    if reference.endswith('.py'):
-        reference = reference[:-3]
+    print reference
+    for ext in ('.py', '.png', '.pdf'):
+        if reference.endswith(ext):
+            reference = reference[:-len(ext)]
+            break
+    if options.has_key('include-source'):
+        template = template_source
+        del options['include-source']
+    else:
+        template = template_no_source
     options = ['      :%s: %s' % (key, val) for key, val in
                options.items()]
     options = "\n".join(options)
diff --git a/doc/users/annotations.rst b/doc/users/annotations.rst
@@ -13,6 +13,7 @@ consider: the location being annotated represented by the argument
 arguments are ``(x,y)`` tuples.
 
 .. plot:: figures/annotation_basic.py
+   :include-source:
    :scale: 75
 
 In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
@@ -73,6 +74,7 @@ keyword args like ``horizontalalignment``, ``verticalalignment`` and
 
 .. plot:: figures/annotation_polar.py
    :scale: 75
+   :include-source:
 
 See the `annotations demo
 <http://matplotlib.sf.net/examples/pylab_examples/annotation_demo.py>`_ for more
diff --git a/doc/users/artists.rst b/doc/users/artists.rst
@@ -135,7 +135,7 @@ drawing of the ticks, tick labels and axis labels.
 
 Try creating the figure below.
 
-.. image:: figures/fig_axes_labels_simple.png
+.. plot:: figures/fig_axes_labels_simple
    :scale: 75
 
 .. _customizing-artists:
@@ -326,7 +326,7 @@ obtain by setting the ``Artist`` transform to :attr:`fig.transFigure
 
     In [195]: fig.canvas.draw()
 
-.. image:: figures/fig_x.png
+.. plot:: figures/fig_x
    :scale: 75
 
 
@@ -606,6 +606,7 @@ the axes and tick properties
 
 .. plot:: figures/fig_axes_customize_simple.py
    :scale: 75
+   :include-source:
 
 
 .. _tick-container:
@@ -643,3 +644,4 @@ dollar signs and colors them green on the right side of the yaxis
 
 .. plot:: figures/dollar_ticks.py
    :scale: 75
+   :include-source:
diff --git a/doc/users/mathtext.rst b/doc/users/mathtext.rst
@@ -273,6 +273,7 @@ Here is an example illustrating many of these features in context.
 
 .. plot:: figures/pyplot_mathtext.py
    :scale: 75
+   :include-source:
 
 
 
diff --git a/doc/users/pyplot_tutorial.rst b/doc/users/pyplot_tutorial.rst
@@ -14,6 +14,7 @@ functions are directed to the current axes
 
 .. plot:: figures/pyplot_simple
    :scale: 75
+   :include-source:
 
 You may be wondering why the x-axis ranges from 0-3 and the y-axis
 from 1-4.  If you provide a single list or array to the
@@ -38,6 +39,7 @@ example, to plot the above with red circles, you would issue
 
 .. plot:: figures/pyplot_formatstr.py
    :scale: 75
+   :include-source:
 
 See the :func:`~matplotlib.pyplot.plot` documentation for a complete
 list of line styles and format strings.  The
@@ -54,6 +56,7 @@ using arrays.
 
 .. plot:: figures/pyplot_three.py
    :scale: 75
+   :include-source:
 
 .. _controlling-line-properties:
 
@@ -159,6 +162,7 @@ scenes.  Below is an script to create two subplots.
 
 .. plot:: figures/pyplot_two_subplots.py
    :scale: 75
+   :include-source:
 
 The :func:`~matplotlib.pyplot.figure` command here is optional because
 ``figure(1)`` will be created by default, just as a ``subplot(111)``
@@ -218,7 +222,7 @@ for a more detailed example)
 
 .. plot:: figures/pyplot_text.py
    :scale: 75
-
+   :include-source:
 
 All of the :func:`~matplotlib.pyplot.text` commands return an
 :class:`matplotlib.text.Text` instance.  Just as with with lines
@@ -264,6 +268,7 @@ these arguments are ``(x,y)`` tuples.
 
 .. plot:: figures/pyplot_annotate.py
    :scale: 75
+   :include-source:
 
 In this basic example, both the ``xy`` (arrow tip) and ``xytext``
 locations (text location) are in data coordinates.  There are a
diff --git a/doc/users/text_intro.rst b/doc/users/text_intro.rst
@@ -57,4 +57,4 @@ these commands in action.
 
 .. plot:: figures/text_commands.py
    :scale: 75
-
+   :include-source:
diff --git a/doc/users/text_props.rst b/doc/users/text_props.rst
@@ -59,3 +59,4 @@ upper right.
 
 .. plot:: figures/text_layout.py
    :scale: 75
+   :include-source:

Original file line number	Diff line number	Diff line change
`@@ -273,6 +273,7 @@ Here is an example illustrating many of these features in context.`
`273`	`273`
`274`	`274`	`.. plot:: figures/pyplot_mathtext.py`
`275`	`275`	`:scale: 75`
	`276`	`+ :include-source:`
`276`	`277`
`277`	`278`
`278`	`279`
Original file line number	Diff line number	Diff line change
`@@ -59,3 +59,4 @@ upper right.`
`59`	`59`
`60`	`60`	`.. plot:: figures/text_layout.py`
`61`	`61`	`:scale: 75`
	`62`	`+ :include-source:`