[Matplotlib-users] plot directive cannot have caption

[Oliver <oli...@gm...>]

Adding a caption to a plot inserted with the `plot` directive from mpl's
sphinxextensions does not work for me, even though the [documentation][1]
says it should be possible.

The relevant ReST snippet:
```
.. plot:: /home/oliver/git/lcp2/code/python/plot_scripts/tangent_circles.py
    :align: center
    :alt: 'Schematic drawing of the two solution methods'

    Schematic drawing showing the two possible solution methods discussed.
```

I'm getting the following traceback:

# Sphinx version: 1.1.3
# Python version: 2.7.3
# Docutils version: 0.9.1 release
# Jinja2 version: 2.6
Traceback (most recent call last):
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/cmdline.py",
line 189, in main
    app.build(force_all, filenames)
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/application.py",
line 204, in build
    self.builder.build_update()
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/builders/__init__.py",
line 196, in build_update
    'out of date' % len(to_build))
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/builders/__init__.py",
line 216, in build
    purple, length):
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/builders/__init__.py",
line 120, in status_iterator
    for item in iterable:
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/environment.py",
line 613, in update_generator
    self.read_doc(docname, app=app)
  File
"/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/environment.py",
line 761, in read_doc
    pub.publish()
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/core.py",
line 221, in publish
    self.settings)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/readers/__init__.py",
line 69, in read
    self.parse()
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/readers/__init__.py",
line 75, in parse
    self.parser.parse(self.input, document)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/__init__.py",
line 162, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 174, in run
    input_source=document['source'])
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 239, in run
    context, state, transitions)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 460, in check_line
    return method(match, context, next_state)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2706, in underline
    self.section(title, source, style, lineno - 1, messages)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 331, in section
    self.new_subsection(title, lineno, messages)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 399, in new_subsection
    node=section_node, match_titles=True)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 286, in nested_parse
    node=node, match_titles=match_titles)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 199, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 239, in run
    context, state, transitions)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 460, in check_line
    return method(match, context, next_state)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2706, in underline
    self.section(title, source, style, lineno - 1, messages)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 331, in section
    self.new_subsection(title, lineno, messages)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 399, in new_subsection
    node=section_node, match_titles=True)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 286, in nested_parse
    node=node, match_titles=match_titles)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 199, in run
    results = StateMachineWS.run(self, input_lines, input_offset)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 239, in run
    context, state, transitions)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/statemachine.py",
line 460, in check_line
    return method(match, context, next_state)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2279, in explicit_markup
    nodelist, blank_finish = self.explicit_construct(match)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2291, in explicit_construct
    return method(self, expmatch)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2034, in directive
    directive_class, match, type_name, option_presets)
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/states.py",
line 2083, in run_directive
    result = directive_instance.run()
  File
"/usr/local/lib/python2.7/dist-packages/docutils-0.9.1-py2.7.egg/docutils/parsers/rst/__init__.py",
line 387, in run
    self.state, self.state_machine)
  File
"/usr/lib/pymodules/python2.7/matplotlib/sphinxext/plot_directive.py", line
210, in plot_directive
    return run(arguments, content, options, state_machine, state, lineno)
  File
"/usr/lib/pymodules/python2.7/matplotlib/sphinxext/plot_directive.py", line
598, in run
    raise RuntimeError("plot:: directive can't have both args and content")
RuntimeError: plot:: directive can't have both args and content

I don't see a reference in the documentation saying it's a feature that was
added in a newer version of mpl.

What am I doing wrong?


[1]:
http://matplotlib.org/devel/documenting_mpl.html#module-matplotlib.sphinxext.plot_directive