[IPython-dev] notebook questions
Sat Sep 17 00:16:46 CDT 2011
I can outline our plans for supporting reST in the notebook.
* The problem with reST is that it can only render entire documents
and not parts of documents. Because of this, it can't be used to
render a single reST text cell in any way that behaves as people
expect. Examples are section headings and references, which are
contextual and require the entire document to make sense of. A more
formal way of putting this is:
rest_render(cell) + rest_render(cell) != rest_render(cell + cell)
Markdown does not suffer from these design limitations and this is why
it is our default for rich text cells in the notebook.
* Obviously reST is very important to the python community and we want
to support reST. Here is how we plan on doing this. The problem is
in the rendering of individual cells. We will implement reST text
cells that simply don't render to HTML in the notebook as the Markdown
cells do. They will remain reST source and be stored in that form in
the notebook format.
* Notebooks with reST text cells can be exported to reST easily and
then rendered to HTML/LaTeX as desired.
* reST document will be able to be imported into the notebook once
this is implemented as well.
The most important point in all of this is that the problem is reST
itself, not the IPython notebook. I actually spent a couple of days
trying to hack reST support into the notebook using various tricks.
At the end of it all my conclusion was a somewhat depressing "wow,
reST is simply not designed for this usage case, but Markdown is a
On Fri, Sep 16, 2011 at 9:17 PM, MinRK <email@example.com> wrote:
> On Fri, Sep 16, 2011 at 20:44, Gael Varoquaux
> <firstname.lastname@example.org> wrote:
>> On Fri, Sep 16, 2011 at 08:41:23PM -0700, MinRK wrote:
>> > I noticed that github allows you to choose between several
>> > different
>> > languages for wiki input so I thought you might have something like
>> > that in mind. I've been using reST for docstrings, sphinx docs,
>> > and
>> > github so I selfishly would prefer not to have to learn another
>> > simplified markup language.
>> > That makes sense, and I expect we will get this request often. The
>> > problem is reST is really a horrible language
>> > for in-browser cell markup (as opposed to full document markup, for
>> > which
>> > it is designed),
>> Actually, reST was originally designed to write docstrings.
> Ah, I didn't know that, given that its design is so much better suited to
> large documents than small isolated text.
>> It seems to me wrong to go with any other markup language, given that the
>> standard in the Python world in reST. It is hard enough to agree on
>> standards, let us rejoice that there is one.
> We thought about this quite a bit, and concluded that markdown was just a
> fit, despite the Python-ness of reST. reST is just a very bad tool for
> interactive, light text markup,
> IPython-dev mailing list
Brian E. Granger
Cal Poly State University, San Luis Obispo
email@example.com and firstname.lastname@example.org
More information about the IPython-dev