ipython/ipython — Issue #888: ReST support in notebooks
Author: minrk
Created: 2011-10-17 18:53:45+00:00
State: open
Labels: htmlnotebook, prio-high, status-active, type-enhancement

This is a place to discuss the requirements of ReST support in the notebooks.

We use markdown now, because what we have are light *text* cells, for annotating your documents. They are essentially rich text + math comment areas. ReST is a great deal more than that, and as such also a great deal more expensive to use (markdown does not require any server communication at all). We initially supported, but removed cell-level ReST support, because it isn't really ReST if each cell is treated as an independent document.

Users should be able to get everything they would expect from ReST when using it in the notebook. That means citations, references, links, and section-levels must be preserved across all cells in a document. As I understand it, this means that all cells must be rendered together. The potential cost of rendering the cells together may mean that render should be a deliberate action, rather than passive on mouseout of every text cell. Further, if ReST has to render the entire document, maybe it should include the code/output as well, and generate the entire document. If we do this, it should probably load in an external preview window, showing the full rendered output, rather than rendering inplace like the markdown cells.

Having markdown as the first-class language for cells, and ReST for full-document output may cause some problems, but it's possible a one-time pass of [pandoc](http://johnmacfarlane.net/pandoc/) for converting md cells to rst would ameliorate that.