Using IPython notebooks for SymPy Examples
Aaron Meurer
One of SymPy's Google Code-In students just completed one of the
"Create Examples/Short Tutorials Using IPython's Notebook (IPython >=
0.12)" tasks (see
http://www.google-melange.com/gci/task/view/google/gci2011/7129292,
and also http://code.google.com/p/sympy/issues/detail?id=2790).
The student's example notebook is very nice, and I really like the
notebook for this medium. I think we should convert all of our
examples in the examples/ directory to use notebooks. Right now, they
are just annotated scripts that print things to the terminal, which
isn't very helpful, because you can read either the code or the
output, but it's hard to see both at the same time.
The issue is how to properly doctest these. Is there an easy way to
doctest IPython notebooks? I am also CC'ing IPython User list.
By the way, this would also improve our testing of the examples if we
can do this. Right now, we just test that they don't produce any
errors, but we don't test the output itself, unless it is also tested
by a regular test (which they all should be, but I suspect not all
are).
Finally, if we do this, I think we should add something in ./setup.py
dist (or similar) that automatically adds pdf copies of all the
notebooks, so that people who don't have IPython can still read the
examples. Is there an easy way to do this?
Aaron Meurer
Aaron Meurer
> On 21 December 2011 14:03, Aaron Meurer <asme...@gmail.com> wrote:
>>
>> The issue is how to properly doctest these. Is there an easy way to
>> doctest IPython notebooks? I am also CC'ing IPython User list.
>
>
> save input and output together.
>
> In the meantime, to turn a notebook into doctests, you could run the cells
> and then use "%hist -pof doctests.py 1-12" (the options mean [p]rompts,
> [o]utput and [f]ile).
This should work for now. Is is possible to generate these files
automatically from the test runner?
>
>>
>> Finally, if we do this, I think we should add something in ./setup.py
>> dist (or similar) that automatically adds pdf copies of all the
>> notebooks, so that people who don't have IPython can still read the
>> examples. Is there an easy way to do this?
>
>
> We should be able to produce a static HTML display of the notebook - I think
> we do this for printing, but I don't know if it's yet possible without
> starting the notebook server. If you wanted to make PDFs from that, you'd
> need something like http://code.google.com/p/wkhtmltopdf/
>
> Another possible approach is to export the notebooks as Python code, and use
> Sphinx to render them. For that matter, maybe Sphinx could be extended to
> load the notebooks directly.
>
> Thomas
Oh, I see. HTML would be better. I thought that it had pdf exporting
built-in, as the GCI student submitted that along with the notebook,
but I guess he just used print preview or something like that.
Aaron Meurer
Aaron Meurer
> On 21 December 2011 14:38, Aaron Meurer <asme...@gmail.com> wrote:
>>
>> > In the meantime, to turn a notebook into doctests, you could run the
>> > cells
>> > and then use "%hist -pof doctests.py 1-12" (the options mean [p]rompts,
>> > [o]utput and [f]ile).
>>
>> This should work for now. Is is possible to generate these files
>> automatically from the test runner?
>
>
> InteractiveShell object, load the notebook, run the cells, and then use that
> magic command to save it as doctests. So it's possible, but a bit involved.
>
> You can load a notebook and save it as Python code with a couple of function
> calls:
> http://ipython.org/ipython-doc/dev/api/generated/IPython.nbformat.current.html#IPython.nbformat.current.read
> http://ipython.org/ipython-doc/dev/api/generated/IPython.nbformat.current.html#IPython.nbformat.current.write
>
> But that isn't quite suitable for doctests - output is in comments, and
> input doesn't have prompts before it. I think it's easy for us to add
> 'doctest' as another format option, but of course it will only be in the
> development version.
>
> Thanks,
> Thomas
Well, the converting of our examples won't actually happen until
someone gets around to doing it anyway. So I think we can reasonably
wait until better doctest support is added, and do it when IPython
0.13 comes out (or whatever version ends up having it). That
certainly would be a killer feature if I could just do "ipython
notebook --doctest file.ipnb" (or something similar), and it would
doctest it. Shall I open an issue for this, or does one already
exist?
Aaron Meurer
Aaron Meurer
this. I may not get around to it any time soon, so if someone else
wants to pick it up, feel free. The main issue now is to simply
convert the examples into notebooks. Hacking up a workaround doctest
solution and html export shouldn't be too hard once that is done.
Aaron Meurer