Expect to see Code cells in Jupyter Outline/ToC

[chrisdias]

Testing #133901

I expected to see Code cells in the ToC/Outline, like I do when I bring up the outline through the command palette.

To bring up the Outline via the command palette, press F1 then type in @. Note the differences in the content with the Outline view.

Part of the confusion for me was that initially I didn't have any markdown (despite the instructions to test... who reads the manual ??) , just code and output, then the Outline view is empty and looks broken.

[IanMatthewHuff]

@chrisdias It's funny, I had the same reaction as you. So the view that I think you (and I expected) to see would be the view if you change this setting from the default:

With this setting on you get code cells in the outline as well.

I feel like this might be a conflict between VS Code users expectations and Jupyter users expectations as the classic Jupyter ToC extension and Jupyterlab ToC extension work with headings. But VS Code users might expect what you and I were looking for. I'll bring this up at the next notebook standup, might be worth discussing what the default should be. Right now, it's just for headings.
https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/toc2/README.html
https://jupyterlab.readthedocs.io/en/stable/user/toc.html

[chrisdias]

I really want to see the outline within the code blocks too rather than each line (if there is one).

[jrieken]

I started this just like @chrisdias wants it to be but got feedback that code-cell in outline are to noisy. I am fine changing it either way. We could also experiment with retrieving the "real" symbol-based outline and add that into the tree

[chrisdias]

+1 on seeing what the "real" symbol-based outline would look like.

[jrieken]

Problem with "real" symbols is that notebook code cells are often just variables and expressions and those traditionally don't show in outlines

[IanMatthewHuff]

We talked about this briefly in notebook standup, and I took a look more at what JupyterLab does. They default to headings, but then allow for either markdown or code cells to be added:
Default:

Markdown:

Code cells:

Looks much nicer with font and weighting versus how our current implementation looks when code cells are added. My vote at least with the current implementation would be to keep the setting as is (code cells off) just to keep the noise down.

[rchiodo]

+1 on code outline. It does look messy with the code, but maybe there's a way to detect language too? Then use the language's icon for the code?

[IanMatthewHuff]

Another point of interest. The default for jupyter is headings. Code shows all markdown cells, that contributes to a bit of the default noise here as well:

With code cells off:

If you break up code cells with explanatory markdown cells (without headings) things can look busy and confusing really quick, even in the default settings.

We also don't pick up html headings, which Jupyter does.

[DonJayamanne]

I'm for just markdowns, when going through a TOC for a document/article/book, i don't expect to see code, i haven't seen that.
Its the heading that i want to see, e.g. I would expect to see a markdown cell such as Http Request Sample or Image Classification Model & then have a code cell that follows that.

See here below for an example (seeing the code will make little to no sense to me, the related heading is what's important & not the code)
If anything the code would add noise (at least for me)

Even if the first line was displayed, it would not help me.
If anything, i think its a poorly structured document & don't expect the TOC to be useful.
From what I understand a large number of users in Jupyter use ipynb as living documents with code/output, hence its generally expected to be well structured (if its to be shared - that's my assumption).

[miguelsolorio]

The problem I see is there are many places where we can show code cells: breadcrumbs, symbol viewer, and outline. If we decide to not show code cells in the outline then we should think about whether it makes sense to not show it in those other areas as well (for consistency). I actually don’t know how many notebook users would leverage those other features.

Would also love for an outline filter option from the view (similar to our other filters).

[DonJayamanne]

would leverage those other features.

Agreed, I don't use breadcrumbs in nbs at all, but use it in regular code files

Would also love for an outline filter option from the view (similar to our other filters).

Sounds like a great idea

[greazer]

If we're trying to decide whether to keep code-cells off in the outline view by default, then I think the answer right now is yes. I mean, the code-cell visualizations in breadcrumbs, symbol viewer and outline feel "messy" and not particularly useful.

Breadcrumb

Symbols

Outline

Breadcrumbs, Symbols, and Outline view were designed to show where symbols are first defined in a source file. That's not how we're using it here.

To add some additional color, I wish I could navigate my source file via the markdown comments in the Interactive Experience. As it stands now, #%% [markdown] "cells" are just ignored in that scenario.

I feel like we're mixing use-cases here and that's what's causing the hangups. In other words, it seems like we need to gracefully incorporate "comment-based navigation" to the Outline View and Breadcrumbs. Symbols should stay only symbols, imo.

In general, code files are typically structured around the code itself. Notebooks are structured around a task that isn't necessarily logically codified than by anything other than comments that break the task into conceptual pieces defined by the author.

I'm not sure I'm making much sense here, but I think there's a thread that needs to be pulled a bit more. So I'm going to commit this comment and wait so see what people think. :)

[jglwiz]

Could the outline panel or symbol panel provide the code cell info?

As a user using screen reader, it is hard to navigate between cells, especially the code cells. The reader only provide cell index info. For example, it reports " cell 19, code cell ...". Could it provides the abstract info such as the first comment line in outline or symbol panel.

In previous version, it provides the function in symbol panel. The symbol panel shows all the first line of each cell as bellow.

When update to new version (jupyter 2024.02), the function is removed. The defination is shown. The info of cells containing function call is missing.

Could the cell abstraction info is provided in outline?

[Yoyokrazy]

@jglwiz Currently the first line of a code cell is the label for code cell entries within the outline view. If you aren't seeing code cells in the outline view, enabling the setting notebook.outline.showCodeCells should fix that.

[Yoyokrazy]

Going to close this as completed as it looks like over time a lot of this has been addressed. The current state of things are as follows:

• Code cells can be enabled or disabled in both breadcrumbs and outline via notebook.outline.showCodeCells and notebook.breadcrumbs.showCodeCells. Default for outline is turned off, and breadcrumbs is turned on.
• Code cells in both the outline and breadcrumbs only show the first line of code in the cell. Users appear to be putting a one line comment to give themselves relevant navigable information (see the comment above)

There is also current work going on to let users control whether or not they will see standard markdown cells in the outline, or if only header information should be shown. That progress along with other nb outline view polish can be tracked via #206308