[IPython-dev] extension to support reStructuredText. how to start?

[Brian Granger]

In the past we have said that we don't have plans on supporting rst
cells. Given recent developments (especially integration with Google
Drive) I think we are even further away from ever supporting rst
cells.

Given this, you will have to implement this yourself outside of the project.

I see two ways you could do this:

A. Modifying the notebook format and UI to build full blown rst cells.

In general, we try to make IPython and the notebook as extensible as
possible. There are two exceptions to this:

1. The kernel message spec.
2. The notebook format

For these two cases our policy is to make it as difficult as possible
to extend and/or modify. The reason we are doing this is that the
second either of these two things change, the resulting entity is no
longer "IPython". The consistency of the message spec and notebook
format are the building blocks that allow the entire architecture to
work together.

If you want to change the notebook format to support Rst cells, then
you should fork IPython and call the resulting project something
entirely different to emphasize that your resulting "notebooks" are
*not* compatible with IPython. Furthermore, we probably won't do
anything to make this easier for you in terms of changing our
architecture or APIs.

B. Using raw cells with a custom UI and renderer that handles the rst logic.

In this case you aren't changing the notebook format and a full blown
fork is not needed. You can still call the notebooks "IPython
Notebooks" and all of our tools will work with them. We *might* even
be willing to add extension points to the existing UI that can be used
to add the rendering logic in custom.js.

I highly recommend B. at this point.













On Sun, Jun 22, 2014 at 5:18 PM, Martín Gaitán <gaitan at gmail.com> wrote:
> Hi everybody.
>
> Last year I proposed a pull request [1] that added support to
> restructuredText in the notebook.  This was dismissed, but with a  very
> interesting debate of core commiters [2]
>
> The idea behind my PR isn't very elegant, but solves the main obstacle: as
> rst is a document wide markup (i.e. it needs to parse the whole document to
> add semantic to each syntax element), we can't render rst cells
> individually. The other point addressed was that there isn't a
> restructuredtext parser in javascript, so we need to render in the backend.
>
> the trick was concatenate every cell as a document adding a mark (a
> comment), process it in the backend via doctutils (I did in the server
> instead the kernel, wrongly), split the output by those marks, and then
> update each cell with its corresponding chunk.
>
> As I'm a heavy rst advocate [3] I would like to implement this as an
> extension. I was looking for some example of a "render hook" based on raw
> data, but I couldn't find one.
> I've found instead the minrk's "gist" extension [4] which use a "comm"
> between the notebook and the kernel, but I couldn't move forward much.
>
> So, where should I start?
> thanks
>
>
> [1] https://github.com/ipython/ipython/pull/4301
> [2] https://www.youtube.com/watch?v=TB7JRe68k84#t=3028
> [3] https://mgaitan.github.io/en/posts/the-reStructuredText-processor.html
> [4] https://raw.github.com/minrk/ipython_extensions/master/gist.py
>
> --
> mgaitan.github.io
> textosypretextos.com.ar
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>



-- 
Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger at calpoly.edu and ellisonbg at gmail.com