sphinxext/numpydoc: wrap Examples in plot:: if they contain matplotlib example code

4 files changed, 43 insertions, 3 deletions

diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/docscrape_sphinx.py
index 7293fc795..5b60567b3 100644
--- a/doc/sphinxext/docscrape_sphinx.py
+++ b/doc/sphinxext/docscrape_sphinx.py
@@ -3,6 +3,8 @@ import sphinx
 from docscrape import NumpyDocString, FunctionDoc, ClassDoc
 
 class SphinxDocString(NumpyDocString):
+    use_plots = False
+
     # string conversion routines
     def _str_header(self, name, symbol='`'):
         return ['.. rubric:: ' + name, '']
@@ -105,6 +107,20 @@ class SphinxDocString(NumpyDocString):
             out += ['   ' + ", ".join(["[%s]_" % item for item in items]), '']
         return out
 
+    def _str_examples(self):
+        examples_str = "\n".join(self['Examples'])
+
+        if (self.use_plots and 'import matplotlib' in examples_str
+                and 'plot::' not in examples_str):
+            out = []
+            out += self._str_header('Examples')
+            out += ['.. plot::', '']
+            out += self._str_indent(self['Examples'])
+            out += ['']
+            return out
+        else:
+            return self._str_section('Examples')
+
     def __str__(self, indent=0, func_role="obj"):
         out = []
         out += self._str_signature()
@@ -118,7 +134,7 @@ class SphinxDocString(NumpyDocString):
         out += self._str_see_also(func_role)
         out += self._str_section('Notes')
         out += self._str_references()
-        out += self._str_section('Examples')
+        out += self._str_examples()
         out = self._str_indent(out,indent)
         return '\n'.join(out)
 
diff --git a/doc/sphinxext/numpydoc.py b/doc/sphinxext/numpydoc.py
index edd58597f..846dd7b85 100644
--- a/doc/sphinxext/numpydoc.py
+++ b/doc/sphinxext/numpydoc.py
@@ -30,6 +30,7 @@ def mangle_docstrings(app, what, name, obj, options, lines,
         lines[:] = title_re.sub('', "\n".join(lines)).split("\n")
     else:
         doc = get_doc_object(obj, what, "\n".join(lines))
+        doc.use_plots = app.config.numpydoc_use_plots
         lines[:] = str(doc).split("\n")
 
     if app.config.numpydoc_edit_link and hasattr(obj, '__name__') and \
@@ -93,6 +94,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.connect('autodoc-process-docstring', mangle_docstrings)
     app.connect('builder-inited', initialize)
     app.add_config_value('numpydoc_edit_link', None, True)
+    app.add_config_value('numpydoc_use_plots', None, False)
 
 #------------------------------------------------------------------------------
 # Monkeypatch sphinx.ext.autodoc to accept argspecless autodocs (Sphinx < 0.5)
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py
index b33da37e2..7b561c8fa 100644
--- a/doc/sphinxext/plot_directive.py
+++ b/doc/sphinxext/plot_directive.py
@@ -160,7 +160,7 @@ TEMPLATE = """
 .. htmlonly::
 
    {% if source_code %}
-       (`Source code <{{ source_link }}>`__)
+   (`Source code <{{ source_link }}>`__)
 
    .. admonition:: Output
       :class: plot-output
@@ -293,9 +293,10 @@ def run(arguments, content, options, state_machine, state, lineno):
     if options['include-source']:
         if is_doctest:
             lines = ['']
+            lines += [row.rstrip() for row in code.split('\n')]
         else:
             lines = ['.. code-block:: python', '']
-        lines += ['    %s' % row.rstrip() for row in code.split('\n')]
+            lines += ['    %s' % row.rstrip() for row in code.split('\n')]
         source_code = "\n".join(lines)
     else:
         source_code = ""
diff --git a/doc/sphinxext/tests/test_docscrape.py b/doc/sphinxext/tests/test_docscrape.py
index 15c9b17f4..4a1f64cf5 100644
--- a/doc/sphinxext/tests/test_docscrape.py
+++ b/doc/sphinxext/tests/test_docscrape.py
@@ -488,3 +488,24 @@ def test_unicode():
 
     """)
     assert doc['Summary'][0] == u'öäöäöäöäöåååå'.encode('utf-8')
+
+def test_plot_examples():
+    doc = SphinxDocString("""
+    Examples
+    --------
+    >>> import matplotlib.pyplot as plt
+    >>> plt.plot([1,2,3],[4,5,6])
+    >>> plt.show()
+    """)
+    assert 'plot::' in str(doc), str(doc)
+
+    doc = SphinxDocString("""
+    Examples
+    --------
+    .. plot::
+    
+       import matplotlib.pyplot as plt
+       plt.plot([1,2,3],[4,5,6])
+       plt.show()
+    """)
+    assert str(doc).count('plot::') == 1, str(doc)