Re: Rewrite of extension to generate examples in documentation
On Wed, May 16, 2012 at 4:59 PM, Stéfan van der Walt <stefan@sun.ac.za>wrote:
Hi Tony
On Tue, May 15, 2012 at 8:15 PM, Tony Yu <tsyu80@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 :-).
... sorry, can't jump at that opportunity right now ;)
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.
Actually, I wasn't wondering whether or not we should ship it; I was wondering if I should strip out all references to it (e.g. the sphinx extension itself, listing it as an extension, setting config parameters for the extension). A quick search suggests that we don't use the plot directive at all.
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
participants (1)
-
Tony Yu