[IPython-dev] using reST for representing the notebook cells+text

[Fernando Perez]

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