Doesn't this break one of the reasons for context mode -- that it allows you to create a figure in one block and then add to it in subsequent ones? This is what the existing :nofigs: and :context: reset features are for.

Aha - I thought that I had missed something.

I can understand the need to build up figures over the course of a few plot directives, and this will break that.

On the other hand, accidentally picking up an old figure seems like a bad idea too, and easy to do.

I think the current answer would be, always do a :context: reset at the top of a new page to avoid this?

That would still not deal with my test case though, where the user called plt.figure() at some point within a page.

Is there another way of avoiding picking up an old figure by accident?

:context: reset will avoid picking up the old figure, but it will also clear everything else. I guess the problem here is that :context: reset resets the state and clears the figures. And maybe you want to do the latter without the former. You can also just explicitly call fig.close()...

Yes, I was doing that with an explicit extra hidden plot_directive at the top of the page, but that's pretty ugly and easy to forget. You'd have to do one of those each time you used plt.figure().

What about closing all but the last figure on the basis it is most unlikely you'd want the first of two figures in the plot directive display?

Or just to add a 'close-existing' option that is false by default?

At least this would be a good explicit solution, although I am sure there will be some surprised users with the default behavior.

close-existing or close-figs seems like a reasonable solution.

OK - I added close-figs and some tests and I think I found and fixed a bug in the context clearing.

All I see here is tests...

I also think you need to white-list the tests so that travis will find them.

I added back the code - bad rebase.

I think I whitelisted the tests?

This looks great, and it's nice to finally have some tests for the plot directive.

Looking at the Travis logs, though, it does seem that the new tests are not actually being run (even though you've added it to the testing list). I may not have a chance to drill down as to why -- I think this is the only tests we have outside of matplotlib.tests, so maybe there's some broken assumption there?

I think the tests aren't being run because sphinx is not installed (the
tests get skipped).

I will try adding sphinx to the dependencies in the travis file.

OK - I believe the tests are running and passing now. The tests revealed a Python 2.6 problem, with an easy fix - ah testing.

Anything more I can do here?

Can you also add a note in https://github.com/matplotlib/matplotlib/tree/master/doc/users/whats_new ?

One of our biggest problems is 'stealth' features that exist but no one knows about.

It seems like it would simpler/cleaner to pass the value of context through to render_figures and do the logic in that function, rather that passing a collection of mutually exclusive kwargs. However, I don't think it is worth making much of a fuss about that at this point in time.

@matthew-brett This needs a re-base

Rebased on master. I hope. Had a few glasses of wine for the new year.