Support outline with notebooks

[kieferrm]

Issue Type: Bug

Using a GH Issues notebook.

1. Open a notebook
2. Cmd+Shift+O => Quick outline appears
3. outline view remains empty

VS Code version: Code - Insiders 1.46.0-insider (da3bf75, 2020-05-19T10:04:14.981Z)
OS version: Darwin x64 18.7.0
Remote OS version: Linux x64 5.3.0-1020-azure

[rebornix]

TOC support in notebook was brought up in sync meetings a couple of times, and I read through users' feedback in microsoft/vscode-jupyter#1348 and did a brief review of how RStudio and Jupyter Lab TOC extension work. The TOC view/pane in RStudio or Jupyter consists of

• Headers from markdown cell
• Gist of code cell

We already support markdown headers in TOC quick pick (ctrl/cmd+shift+o) and the only missing part is the Outline view doesn't show the same symbols info from the notebook yet. @rchiodo can you help verify if my understand is correct? IMHO supporting markdown headers (w/, or w/o code cell symbols) in both quick pick and outline view solves the problem users are running into (having trouble navigating in long notebooks).

[rchiodo]

I think it's more than that (customer's expectations). Not sure even if we had symbols in the outline view if that would meet expectations.

See all the stuff the TOC extension can do here:
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/README.html

Perhaps this needs some QP studies to confirm, but I think the first problem is finding the 'outline' tab or the quick pick. Users won't expect to look there. I didn't even know about the CTRL+SHIFT+O option.

[rchiodo]

This may be as simple as adding a button into the notebook UI like the jupyter extension does (which just opens the outline)

[rebornix]

@rchiodo thanks for the link!

but I think the first problem is finding the 'outline' tab or the quick pick

While doing my investigation in Jupyter Lab and RStudio, I found myself have to google "TOC in Jupyter/RStudio" as I can't find them myself (I'm not using the traditional UI so I missed the "table of contents" button). It has some learning curve and different Jupyter frontend varies. The outline view in VS Code might share the same discoverability issue but it's well known to existing VS Code users.

The features listed in https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/README.html are (excluding features in exporting HTML)

• Dedicated window for TOC
  • jupyter-lab: floating window and sidebar.
  • vscode: quick pick and view.
• Notebook scrolling and Collapsing sections
  • jupyter-lab: folding state of the TOC and the document can be synced
  • vscode: toc and document have different folding state management
  • click toc entry to navigate works in both
• Jupyter lab toc also supports following actions/configuration
  • toggles automatic numerotation of all header lines (e.g., change # header to 1. header)
  • maximum depth of headers
  • numbering of headers
  • marking toc item of first header displayed on viewport when scrolling the notebook (auto scroll sync)
  • skipping h1 headers

They are good features but IMHO none of them are critical/blocking. My suggestion for this is making sure the outline view has the right info, and then we can explore how we can enrich it (for example, we can explore if we can contribute actions to TOC entries, just like every other tree view).

@jrieken may I ask again why the outline view can't get the symbols info from the notebook?

[rchiodo]

I think this part is crux:

The outline view in VS Code might share the same discoverability issue but it's well known to existing VS Code users.

I don't know that jupyter users are existing VS code users. Or at least we're trying to get those that aren't. But a QP study would prove/disprove this hypothesis.

[rebornix]

yup, let's introduce this to them first and see what's the feedback. I think for users in microsoft/vscode-jupyter#1348, VS Code is not foreign to them.

[rebornix]

It just occurred to me that we have this breadcrumb feature in regular editor:

We can also adopt the notebook toc info in this.

[jrieken]

@jrieken may I ask again why the outline view can't get the symbols info from the notebook?

There are no blocking reasons except for this being a lot of work and therefore we kinda postponed it. Today, the outline (and breadcrumbs) model is based around a single text document and that would need to be changed. With quick outline I have explored some TOC provider ideas and that can in theory be driving the outline and breadcrumbs as well.

So, given the amount of work this requires we should be somewhat certain that we want this. Tho, I'd say it would be nice, outline, breadcrumbs and quick outline would work for notebooks and "normal" editors and for notebooks information could be "nested", like high level cell outline and then per cell a document outline

[jrieken]

Done.