Rewrite of extension to generate examples in documentation

[Stéfan van der Walt]

Hi Tony

On Tue, May 15, 2012 at 8:15 PM, Tony Yu <tsyu80 at gmail.com> wrote:
> P.S. I only recently learned of an IPython project to provide similar
> functionality. I'm not sure if there are any lasting advantages to using
> `plot2rst` (compared to the IPython notebook; one disadvantage is that
> `plot2rst` doesn't capture terminal output), but the immediate advantage is
> that it's a drop-in replacement for `gen_rst`.

I'm glad you mentioned this; I've been using nbconvert
(https://github.com/ipython/nbconvert), and I think that would be a
good way forward: not only can it produce good looking PDFs, but it
can also do the HTML, and allows us to edit examples easily.

However, someone has to do the work to integrate this, so I'm not sure
it's the best solution *right now* (unless you are feeling
particularly productive :-).

> P.P.S. I noticed that we include the `plot_directive` extension, but I don't
> believe it's used. I can remove this as part of the PR if someone confirms.

I thought this was for when matplotlib (sphinx?) didn't ship it, but
since we rely on matplotlib 1 and sphinx anyway, you can go ahead.

> P.P.P.S. This PR should probably wait until after releasing 0.6, since it's
> a pretty big change. Plus, it's just documentation so it will be up-to-date
> on the website; it's less important that it's up-to-date in a user's
> install.

That's probably sensible; and for now I'd also like to explore how
much effort it would be to integrate notebooks in this pipeline, so
waiting until 0.7 should give us time.

Thanks!
Stéfan