An alternative solution would be to do everything that is needed for a given figure within a single code block, but that's not as flexible as this solution.

It would be great to add tests, preferentially both with matplotlib and mayavi. Not a matplotlib expert, I could not find something that goes wrong because of closing all the figures at the end of a block, suggestions welcome!

I'm not sure about whether it causes problems with matplotlib but it definitely does for mayavi. And if we're going to do it for one, we might as well do it for both to be safe.

I'll look into the Travis failure and try to add tests soon.

Okay, tests added. I put in a bunch of fixes for Windows-related building because I'm on my Windows dev machine currently. It would be worth adding AppVeyor testing at some point and cleaning up Windows support properly.

travis is not happy :(

All better

I'll will start with a consistency check of how we want to present output, and how we should understand the notebook styled examples or code and outputs interleaved with prose.
Let's put this simple script to test

# -*- coding: utf-8 -*-
"""
The sin function with a phase shift
===================================

"""

# Code source: Óscar Nájera
# License: BSD 3 clause

import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)
plt.plot(x, y, label=r'$\sin(x)$')

###############################################################################
# now put an angle
y = np.sin(x + np.pi / 4)
plt.plot(x, y, lw=2, label=r'$\sin(x+\pi/4)$')

plt.legend(loc=0)
plt.xlabel('$x$')
plt.ylabel('$\sin(x)$')
plt.show()

If we run this directly from the command line we get a window to pop up with the 2 curves in the same figure. If I run this in the gallery at master I get 2 figures, each one holds 1 curve.

And the rendered Jupyter notebook produces a similar output, as indeed we have defined 2 blocks.

Running this PR I get a not consistent result, at least in my linux PC the second block does not show any output, and that I assume is totally unwanted. I would have expected the second figure to be a composition of the first and second plot instructions. Showing 2 curves in the figure.

Now to the core of my discussion. I do see the intention in a tutorial to show how every new line of code adds to the drawn figure and so to show each code block as an intermediate step. But I feel in a notebook styled example we should restrict ourselves to plot individually what each block is declaring. Especially since the examples are targeted for education purposes, that once the students try out the jupyter notebook file they shall get the same output. To me the easiest way to accomplish this is to just close all figures after saving them for each block.

Second thought, is that jupyter notebooks do allow to recover the plotted figure from the previous cell and compose on top of that, but the syntax is quite involved and I would be even more against to support that for our simple set of examples when just rewriting the plot instructions is so simple.

Third thought is that if we want to support accumulating the figures. I would rather first include a flag to tell sphinx-gallery to deviate from the behavior of making each block individual and stop closing figures after each block. Then make the author of the script be responsible for which figures are open(alive), and which he wants to close. In that case sphinx-gallery shall save and show for each block all active figures. I think this would also avoid the monkey patching of the figure object, simplify the numbering/naming of saved figures as is just a counter. And as put in the current PR comment, recapturing a picture in this case is trivial.

I do agree there is some tension between seeing the example as a Jupyter notebook and seing it as a script, for example when you do multiple plt.plot in different cells, it is not clear to me what the behaviour should be in this case.

In @Eric89GXL's case though, I think that we are not in such a tricky case. IIUC he plots two different figures in two different cells. The problem is that closing the first figure (let's call it fig) make the variable fig not usable any more (to be honest it could well be considered as a mayavi bug, but that may be a very naive interpretation of the problem given that I know close to nothing about mayavi). The second plot tries to use fig, not to plot on top of the first figure but to reuse its "viewport transformation" and that's where the problem happens.

I would be in favour of not closing the figures since that seems to be a useful work-around in this case, unless we can spot a real blocker in the fine case of trying to plot figures in different cells.

I would leave plotting on top of an existing figure and recapturing as undefined behaviour for now.

I would be in favour of not closing the figures since that seems to be a useful work-around in this case, unless we can spot a real blocker in the fine case of trying to plot figures in different cells.

But for mayavi or for matplotlib?

But for mayavi or for matplotlib?

I guess for both, be it only for consistency reasons.

Closing for now until consensus

I am +1 on closing the figures only at the end of the script.

@Eric89GXL what is your current work-around this in MNE-python?

In the example where we needed to modify an existing (mayavi) figure, we instead recreated it in the next block and modified it.

In the example where we needed to modify an existing (mayavi) figure, we instead recreated it in the next block and modified it.

So you have some duplication (the lines to create the figure) in your example?

Yeah, that's what we ended up going with I think