search

att / rcloud

Collaborative data analysis and visualization
http://rcloud.social
MIT License
431 stars 142 forks source link

Feature Request: Table of Contents for a notebook #929

Open sisukapalli opened 10 years ago

sisukapalli commented 10 years ago

I think it would be nice to have a Table of Contents (TOC) feature for a notebook. It will make the notebooks more easy to read and navigate. A user can click on an entry in the TOC and go to that cell. Numbering and sections hierarchy helps in organizing too.

I had to do this to share one messy set of shell scripts, documentation, csv files, python code, hive scripts, etc., and pulling them into a notebook helped me streamline the workflow and having a TOC helped me organize things easily. I had to do minor hacks with two modules in IPython (nbtoc and secnum extensions) to get the piece working. Now, I am able to export it as a static HTML with a reasonable layout...

It would be nice to have the TOC feature in RCloud. I am willing to adapt this logic. However, some logistics issues are present on what approach is best suited for RCloud. Many possible paths:

  1. Have a special header cells like IPython does (pros: clean; cons: too much of a change to user experience)
  2. Use headers from markdown cells (pros: easy; cons: it may be tough to specify that a header should not be included in TOC - like LaTeX's \section*{} without additional syntax)
  3. Pick up all headers (pros: we can even have a nicer experience with toc, list-of-figures, etc.; cons: needs running of the whole notebook; cons: too much LaTeX-ish piece)

I included a screen shot from a toy notebook here. The layout is fairly simple but works (there is scope for substantial improvements -- typography, layout, etc.). Please note that I manually shrinked the plots in IPython to make the main cells fit the screen...

toc-feature-request .

gordonwoodhull commented 10 years ago

It's a good idea. I guess I would side with the automatically generated kind, generated from headers like on Wikipedia or some Markdown TOC implementations.

However, as you note, there might have to be some tricks to make the pieces of Markdown in different cells be numbered together. And also as you say, it would either require running the whole notebook or some sort of caching.

We are planning to have some sort of result/output caching like IPython has; perhaps this will help.

I have no idea how to get the numbering right in the face of cell reordering, but where there's a will...

sisukapalli commented 10 years ago

Thanks about result caching note... It will make life very easy (and has additional benefits like publishing notebooks as html with some "representative results").

Fully agree about how hard it is to get numbering after reordering. The IPython stuff is pretty mundane and refreshes after rerunning the TOC generation. It is simple enough if we do not insist on realtime numbering.