Menu
▾
▴
SF.net SVN: matplotlib: [5503] trunk/matplotlib/doc
|
From: <md...@us...> - 2008-06-13 14:10:28
|
Revision: 5503
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5503&view=rev
Author: mdboom
Date: 2008-06-13 07:10:02 -0700 (Fri, 13 Jun 2008)
Log Message:
-----------
Add plot directive to include inline plots and their source.
Modified Paths:
--------------
trunk/matplotlib/doc/conf.py
trunk/matplotlib/doc/make.py
trunk/matplotlib/doc/users/annotations.rst
trunk/matplotlib/doc/users/artists.rst
trunk/matplotlib/doc/users/figures/make.py
trunk/matplotlib/doc/users/mathtext.rst
trunk/matplotlib/doc/users/pyplot_tutorial.rst
trunk/matplotlib/doc/users/text_intro.rst
trunk/matplotlib/doc/users/text_props.rst
Added Paths:
-----------
trunk/matplotlib/doc/sphinxext/only_directives.py
trunk/matplotlib/doc/sphinxext/plot_directive.py
Modified: trunk/matplotlib/doc/conf.py
===================================================================
--- trunk/matplotlib/doc/conf.py 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/conf.py 2008-06-13 14:10:02 UTC (rev 5503)
@@ -27,7 +27,8 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['mathpng', 'math_symbol_table', 'sphinx.ext.autodoc']
+extensions = ['mathpng', 'math_symbol_table', 'sphinx.ext.autodoc',
+ 'only_directives', 'plot_directive']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
Modified: trunk/matplotlib/doc/make.py
===================================================================
--- trunk/matplotlib/doc/make.py 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/make.py 2008-06-13 14:10:02 UTC (rev 5503)
@@ -24,24 +24,32 @@
def html():
check_build()
figs()
- os.system('sphinx-build -b html -d build/doctrees . build/html')
+ if os.system('sphinx-build -b html -d build/doctrees . build/html'):
+ raise SystemExit("Building HTML failed.")
+ figures_dest_path = 'build/html/users/figures'
+ if os.path.exists(figures_dest_path):
+ shutil.rmtree(figures_dest_path)
+ shutil.copytree('users/figures', figures_dest_path)
+
def latex():
check_build()
figs()
if sys.platform != 'win32':
# LaTeX format.
- os.system('sphinx-build -b latex -d build/doctrees . build/latex')
+ if os.system('sphinx-build -b latex -d build/doctrees . build/latex'):
+ raise SystemExit("Building LaTeX failed.")
# Produce pdf.
os.chdir('build/latex')
# Copying the makefile produced by sphinx...
- os.system('pdflatex Matplotlib.tex')
- os.system('pdflatex Matplotlib.tex')
- os.system('makeindex -s python.ist Matplotlib.idx')
- os.system('makeindex -s python.ist modMatplotlib.idx')
- os.system('pdflatex Matplotlib.tex')
+ if (os.system('pdflatex Matplotlib.tex') or
+ os.system('pdflatex Matplotlib.tex') or
+ os.system('makeindex -s python.ist Matplotlib.idx') or
+ os.system('makeindex -s python.ist modMatplotlib.idx') or
+ os.system('pdflatex Matplotlib.tex')):
+ raise SystemExit("Rendering LaTeX failed.")
os.chdir('../..')
else:
Added: trunk/matplotlib/doc/sphinxext/only_directives.py
===================================================================
--- trunk/matplotlib/doc/sphinxext/only_directives.py (rev 0)
+++ trunk/matplotlib/doc/sphinxext/only_directives.py 2008-06-13 14:10:02 UTC (rev 5503)
@@ -0,0 +1,87 @@
+#
+# A pair of directives for inserting content that will only appear in
+# either html or latex.
+#
+
+from docutils.nodes import Body, Element
+from docutils.writers.html4css1 import HTMLTranslator
+from sphinx.latexwriter import LaTeXTranslator
+from docutils.parsers.rst import directives
+
+class html_only(Body, Element):
+ pass
+
+class latex_only(Body, Element):
+ pass
+
+def run(content, node_class, state, content_offset):
+ text = '\n'.join(content)
+ node = node_class(text)
+ state.nested_parse(content, content_offset, node)
+ return [node]
+
+try:
+ from docutils.parsers.rst import Directive
+except ImportError:
+ from docutils.parsers.rst.directives import _directives
+
+ def html_only_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ return run(content, html_only, state, content_offset)
+
+ def latex_only_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ return run(content, latex_only, state, content_offset)
+
+ for func in (html_only_directive, latex_only_directive):
+ func.content = 1
+ func.options = {}
+ func.arguments = None
+
+ _directives['htmlonly'] = html_only_directive
+ _directives['latexonly'] = latex_only_directive
+else:
+ class OnlyDirective(Directive):
+ has_content = True
+ required_arguments = 0
+ optional_arguments = 0
+ final_argument_whitespace = True
+ option_spec = {}
+
+ def run(self):
+ self.assert_has_content()
+ return run(self.content, self.node_class,
+ self.state, self.content_offset)
+
+ class HtmlOnlyDirective(OnlyDirective):
+ node_class = html_only
+
+ class LatexOnlyDirective(OnlyDirective):
+ node_class = latex_only
+
+ directives.register_directive('htmlonly', HtmlOnlyDirective)
+ directives.register_directive('latexonly', LatexOnlyDirective)
+
+def setup(app):
+ app.add_node(html_only)
+ app.add_node(latex_only)
+
+ # Add visit/depart methods to HTML-Translator:
+ def visit_perform(self, node):
+ pass
+ def depart_perform(self, node):
+ pass
+ def visit_ignore(self, node):
+ node.children = []
+ def depart_ignore(self, node):
+ node.children = []
+
+ HTMLTranslator.visit_html_only = visit_perform
+ HTMLTranslator.depart_html_only = depart_perform
+ HTMLTranslator.visit_latex_only = visit_ignore
+ HTMLTranslator.depart_latex_only = depart_ignore
+
+ LaTeXTranslator.visit_html_only = visit_ignore
+ LaTeXTranslator.depart_html_only = depart_ignore
+ LaTeXTranslator.visit_latex_only = visit_perform
+ LaTeXTranslator.depart_latex_only = depart_perform
Added: trunk/matplotlib/doc/sphinxext/plot_directive.py
===================================================================
--- trunk/matplotlib/doc/sphinxext/plot_directive.py (rev 0)
+++ trunk/matplotlib/doc/sphinxext/plot_directive.py 2008-06-13 14:10:02 UTC (rev 5503)
@@ -0,0 +1,85 @@
+"""A special directive for including a matplotlib plot.
+
+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
+"""
+
+from docutils.parsers.rst import directives
+
+try:
+ # docutils 0.4
+ from docutils.parsers.rst.directives.images import align
+except ImportError:
+ # docutils 0.5
+ from docutils.parsers.rst.directives.images import Image
+ align = Image.align
+
+options = {'alt': directives.unchanged,
+ 'height': directives.length_or_unitless,
+ 'width': directives.length_or_percentage_or_unitless,
+ 'scale': directives.nonnegative_int,
+ 'align': align,
+ 'class': directives.class_option}
+
+template = """
+.. literalinclude:: %(reference)s.py
+
+.. htmlonly::
+
+ .. image:: %(reference)s.png
+ :target: %(reference)s.hires.png
+%(options)s
+
+ `[source] <%(reference)s.py>`_
+
+.. latexonly::
+ .. image:: %(reference)s.pdf
+%(options)s
+
+"""
+
+def run(arguments, options, state_machine, lineno):
+ reference = directives.uri(arguments[0])
+ if reference.endswith('.py'):
+ reference = reference[:-3]
+ options = [' :%s: %s' % (key, val) for key, val in
+ options.items()]
+ options = "\n".join(options)
+ lines = template % locals()
+ lines = lines.split('\n')
+
+ state_machine.insert_input(
+ lines, state_machine.input_lines.source(0))
+ return []
+
+try:
+ from docutils.parsers.rst import Directive
+except ImportError:
+ from docutils.parsers.rst.directives import _directives
+
+ def plot_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ return run(arguments, options, state_machine, lineno)
+ plot_directive.__doc__ = __doc__
+ plot_directive.arguments = (1, 0, 1)
+ plot_directive.options = options
+
+ _directives['plot'] = plot_directive
+else:
+ class plot_directive(Directive):
+ required_arguments = 1
+ optional_arguments = 0
+ final_argument_whitespace = True
+ option_spec = options
+ def run(self):
+ return run(self.arguments, self.options,
+ self.state_machine, self.lineno)
+ plot_directive.__doc__ = __doc__
+
+ directives.register_directive('plot', plot_directive)
+
Modified: trunk/matplotlib/doc/users/annotations.rst
===================================================================
--- trunk/matplotlib/doc/users/annotations.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/annotations.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -12,9 +12,7 @@
``xy`` and the location of the text ``xytext``. Both of these
arguments are ``(x,y)`` tuples.
-.. literalinclude:: figures/annotation_basic.py
-
-.. image:: figures/annotation_basic.png
+.. plot:: figures/annotation_basic.py
:scale: 75
In this example, both the ``xy`` (arrow tip) and ``xytext`` locations
@@ -73,9 +71,7 @@
``fontsize are passed from the `~matplotlib.Axes.annotate` to the
``Text`` instance
-.. literalinclude:: figures/annotation_polar.py
-
-.. image:: figures/annotation_polar.png
+.. plot:: figures/annotation_polar.py
:scale: 75
See the `annotations demo
Modified: trunk/matplotlib/doc/users/artists.rst
===================================================================
--- trunk/matplotlib/doc/users/artists.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/artists.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -604,9 +604,7 @@
Here is an example, not recommended for its beauty, which customizes
the axes and tick properties
-.. literalinclude:: figures/fig_axes_customize_simple.py
-
-.. image:: figures/fig_axes_customize_simple.png
+.. plot:: figures/fig_axes_customize_simple.py
:scale: 75
@@ -643,7 +641,5 @@
Here is an example which sets the formatter for the upper ticks with
dollar signs and colors them green on the right side of the yaxis
-.. literalinclude:: figures/dollar_ticks.py
-
-.. image:: figures/dollar_ticks.png
+.. plot:: figures/dollar_ticks.py
:scale: 75
Modified: trunk/matplotlib/doc/users/figures/make.py
===================================================================
--- trunk/matplotlib/doc/users/figures/make.py 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/figures/make.py 2008-06-13 14:10:02 UTC (rev 5503)
@@ -7,27 +7,37 @@
mplshell = IPython.Shell.MatplotlibShell('mpl')
+formats = [('png', 100),
+ ('hires.png', 200),
+ ('pdf', 72)]
+
def figs():
print 'making figs'
import matplotlib.pyplot as plt
for fname in glob.glob('*.py'):
if fname==__file__: continue
basename, ext = os.path.splitext(fname)
- outfile = '%s.png'%basename
+ outfiles = ['%s.%s' % (basename, format) for format, dpi in formats]
+ all_exists = True
+ for format, dpi in formats:
+ if not os.path.exists('%s.%s' % (basename, format)):
+ all_exists = False
+ break
- if os.path.exists(outfile):
- print ' already have %s'%outfile
- continue
+ if all_exists:
+ print ' already have %s'%fname
else:
print ' building %s'%fname
- plt.close('all') # we need to clear between runs
- mplshell.magic_run(basename)
- plt.savefig(outfile)
+ plt.close('all') # we need to clear between runs
+ mplshell.magic_run(basename)
+ for format, dpi in formats:
+ plt.savefig('%s.%s' % (basename, format), dpi=dpi)
print 'all figures made'
def clean():
- patterns = ['#*', '*~', '*.png', '*pyc']
+ patterns = (['#*', '*~', '*pyc'] +
+ ['*.%s' % format for format, dpi in formats])
for pattern in patterns:
for fname in glob.glob(pattern):
os.remove(fname)
Modified: trunk/matplotlib/doc/users/mathtext.rst
===================================================================
--- trunk/matplotlib/doc/users/mathtext.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/mathtext.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -271,9 +271,7 @@
Here is an example illustrating many of these features in context.
-.. literalinclude:: figures/pyplot_mathtext.py
-
-.. image:: figures/pyplot_mathtext.png
+.. plot:: figures/pyplot_mathtext.py
:scale: 75
Modified: trunk/matplotlib/doc/users/pyplot_tutorial.rst
===================================================================
--- trunk/matplotlib/doc/users/pyplot_tutorial.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/pyplot_tutorial.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -12,12 +12,9 @@
keeps track of the current figure and plotting area, and the plotting
functions are directed to the current axes
-.. literalinclude:: figures/pyplot_simple.py
-
-.. image:: figures/pyplot_simple.png
+.. plot:: figures/pyplot_simple
:scale: 75
-
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
:func:`~matplotlib.pyplot.plot` command, matplotlib assumes it a
@@ -39,9 +36,7 @@
The default format string is 'b-', which is a solid blue line. For
example, to plot the above with red circles, you would issue
-.. literalinclude:: figures/pyplot_formatstr.py
-
-.. image:: figures/pyplot_formatstr.png
+.. plot:: figures/pyplot_formatstr.py
:scale: 75
See the :func:`~matplotlib.pyplot.plot` documentation for a complete
@@ -57,9 +52,7 @@
plotting several lines with different format styles in one command
using arrays.
-.. literalinclude:: figures/pyplot_three.py
-
-.. image:: figures/pyplot_three.png
+.. plot:: figures/pyplot_three.py
:scale: 75
.. _controlling-line-properties:
@@ -164,9 +157,7 @@
to worry about this, because it is all taken care of behind the
scenes. Below is an script to create two subplots.
-.. literalinclude:: figures/pyplot_two_subplots.py
-
-.. image:: figures/pyplot_two_subplots.png
+.. plot:: figures/pyplot_two_subplots.py
:scale: 75
The :func:`~matplotlib.pyplot.figure` command here is optional because
@@ -225,9 +216,7 @@
are used tox add text in the indicated locations (see :ref:`text-intro`
for a more detailed example)
-.. literalinclude:: figures/pyplot_text.py
-
-.. image:: figures/pyplot_text.png
+.. plot:: figures/pyplot_text.py
:scale: 75
@@ -273,9 +262,7 @@
the argument ``xy`` and the location of the text ``xytext``. Both of
these arguments are ``(x,y)`` tuples.
-.. literalinclude:: figures/pyplot_annotate.py
-
-.. image:: figures/pyplot_annotate.png
+.. plot:: figures/pyplot_annotate.py
:scale: 75
In this basic example, both the ``xy`` (arrow tip) and ``xytext``
Modified: trunk/matplotlib/doc/users/text_intro.rst
===================================================================
--- trunk/matplotlib/doc/users/text_intro.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/text_intro.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -55,8 +55,6 @@
variety of font and other properties. The example below shows all of
these commands in action.
-.. literalinclude:: figures/text_commands.py
-
-.. image:: figures/text_commands.png
+.. plot:: figures/text_commands.py
:scale: 75
Modified: trunk/matplotlib/doc/users/text_props.rst
===================================================================
--- trunk/matplotlib/doc/users/text_props.rst 2008-06-13 12:46:20 UTC (rev 5502)
+++ trunk/matplotlib/doc/users/text_props.rst 2008-06-13 14:10:02 UTC (rev 5503)
@@ -57,7 +57,5 @@
bounding box, with 0,0 being the lower left of the axes and 1,1 the
upper right.
-.. literalinclude:: figures/text_layout.py
-
-.. image:: figures/text_layout.png
+.. plot:: figures/text_layout.py
:scale: 75
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
