BUG: Plot(s) not rendered if docstring ends with normal text after show command

[lagru]

I'm not entirely sure whether this is a bug in numpydoc or matplotlib.sphinxext (where the error message happens). This is my best guess right now and I hope someone with more insight into the inner workings of both can pinpoint the bug.

Bug description

When using the plot directive implicitly in docstrings sometimes the plots are not included in the rendered HTML documentation. This happens when the docstring ends with a normal text line after the >>> plt.show() statement. It seems like The cause lies in how SphinxDocString parses the input (see snippets below). In this special case the functions in plot_directive.py won't prefix the last line with #. As a consequence the last line raises an exception on line 524 when calling six.exec_(code, ns) in plot_directive.py (function run_code).

Reproduction

I have created a minimal dummy project to demonstrate the behavior:
https://github.com/lagru/docstring-plot-bug-demo

As stated the possible cause might lie here:

from numpydoc.docscrape_sphinx import SphinxDocString
doc = SphinxDocString("""
Examples
--------
>>> import matplotlib.pyplot as plt
>>> plt.plot([1,2,3],[4,5,6])
>>> plt.show()

Some text.
""", config=dict(use_plots=True))
print(doc)

which yields

.. rubric:: Examples

.. plot::

    >>> import matplotlib.pyplot as plt
    >>> plt.plot([1,2,3],[4,5,6])
    >>> plt.show()
    
    Some text.

However I would expect this output:

.. rubric:: Examples

.. plot::

    >>> import matplotlib.pyplot as plt
    >>> plt.plot([1,2,3],[4,5,6])
    >>> plt.show()
    
Some text.

Note how the last line isn't part of the plot:: directive in contrast to the actual output.

Other info

Setup
OS: Manjaro 17.1.7, x86_64 Linux 4.14.30-1-MANJARO
python 3.6.5
numpydoc 0.7.0
sphinx 1.7.2
matplotlib 2.2.2

[pv]

The restructuredtext markup:

>>> plt.show()
Some text.

means that "Some text." is a part of the doctest block (in particular, it's the output from the previous command) --- the newline is necessary if you want it to be parsed differently.

So this seems to be working as expected per spec.

[pv]

However, I would expect the plot:: directive to produce output even if there are trailing doctest output lines, so maybe there is a bug there.

[lagru]

Actually that's a typo by me. I forgott to add the blank line in-between. The snippet should read: ``` from numpydoc.docscrape_sphinx import SphinxDocString doc =SphinxDocString(""" Examples --------

>> import matplotlib.pyplot as plt >> plt.plot([1,2,3],[4,5,6]) >> plt.show()

Some text. """, config=dict(use_plots=True)) print(doc) ``` (Updated description in first post)

[pv]

Right, however also that should still render the plot since it's still valid doctest input.

[lagru]

However, I would expect the plot:: directive to produce output even if there are trailing doctest output lines, so maybe there is a bug there.

Meaning I should raise an issue with matplotlib? I will do that and ask whether they intend to support this pattern (their documentation does only feature basic examples). If not this might be something that numpydoc needs to handle itself.