[IPython-dev] using reST for representing the notebook cells+text
Fernando Perez
fperez.net at gmail.com
Wed Feb 24 11:39:13 EST 2010
On Wed, Feb 24, 2010 at 2:52 AM, Brian Granger <ellisonbg.net at gmail.com> wrote:
>
> In many respects it seems almost perfect. But, one day recently I was
> thinking about how successful Mathematica's notebook continues to be. So I
> began to look more at the Mathematica notebook format. Amazingly, the
> Mathematica notebook format is a plain text file that itself is *valid
> Mathematica code*. This id documented here:
>
> http://reference.wolfram.com/mathematica/guide/LowLevelNotebookProgramming.html
>
> For examples a simple notebook with one text cell is just:
>
> Notebook[{Cell['Here is my text', 'Text']}]
>
> Everything - input cells, output cells, static images and all are
> represented in this way and embedded in the plain text notebook file. The
> Python generalization of this would be the following:
>
> * A Python notebook is plain text, importable Python code.
> * That code is simply a tree of objects that declare the relevant parts of
> the notebook.
>
> This has a number of advantages:
>
> * A notebook can be imported, manipulated and run by anyone who has the
> support code (the notebook module that defines the relevant classes).
> * A notebook doesn't need to be parsed. It is valid Python and can be
> imported or exec'd. Once that is done, you have the full notebook in
> memory. You can immediately do anything you want with it.
> * The various Notebook, Cell, Image, etc. classes can know about how to
> output to various formats, latex, html, reST, XML, etc:
>
> import mynotebook
> mynotebook.notebook.export('rest')
>
> * Each individual format (HTML, reST, latex) has weaknesses. If you pick
> any one to be *the* notebook format, you are building those weaknesses into
> your design. A pure python based notebook format won't suffer from that
> syndrome.
> * It is a clean separation of the model (Notebook, Cell, Image, etc.) and
> the view (HTML, reST, etc.). Picking HTML or reST for the notebook format
> confuses (at some level) the model and view...
> * Third party code can define new Notebook elements that specify how they
> can be rendered in different contexts. For example, matplotlib could ship a
> Figure element that knows how to render itself as a native PyQt GUI, a
> static image, a web page, etc.
> * A notebook remains a single plain text file that anyone can edit - even if
> it has embedded images. Neither HTML nor reST have the ability to inline
> graphics in plain text files. While I love reST, it is a pain that I need
> an entire directory of files to render a single Sphinx doc.
I had just composed a reply offline (I had no network for a bit) but I
just now saw that in the interim, Robert said pretty much what I had
written. Since python isn't lisp(ish), I'm also not convinced that a
code-as-data approach will be all that useful for us. I do think rest
can be the next best thing for us, since at least we have parsing
machinery (docutils), extensible document tools (sphinx), and any
tools on top of rest/sphinx would likely get a lot of reuse.
I added your notes to the ipython docs for reference though, it will
be good to have these notes all in one place.
Cheers,
f
More information about the IPython-dev
mailing list