TOC for .py files with percent markup

[brettcannon]

Discussed in #15990

^{Originally posted by syagev April 19, 2021}
I suggest to have a TOC available for .py files with percent markup. I guess for that we'll need to have the user select which kind of "Outline" view is of interest - the one for regular code files (which will not pickup e.g. markdown cells), or the one adjusted for notebooks.

My use case - in our team we manage a big .py file that acts as a sort of "catalog" of useful and relatively independent cells. This has to go under source control for version management and collaboration. The typical workflow is then to open an Interactive Window and execute a few of the cells of interest. So for finding these cells in the large file the described TOC is useful.

Originally posted by @syagev in microsoft/vscode-jupyter#1348 (comment)

Also opened as issue under vscode-jupyter microsoft/vscode-jupyter#5552 since I'm not sure where the right place is.

[brettcannon]

Thanks for the feature request! We are going to give the community 60 days from when this issue was created to provide 5 👍 upvotes on the opening comment to gauge general interest in this idea. If there's enough upvotes then we will consider this feature request in our future planning. If there's unfortunately not enough upvotes then we will close this issue.

[GitHunter0]

I believe most users are still not aware of this new issue, it is such an indispensable feature that it would be shocking if it cannot get 5 upvotes. To me it is a no-brainer that every single IDE should have it.

Thanks for opening this issue.

[GitHunter0]

Just repeating the 2 suggestions I made in another issue.

(1) The hierarchical section system of Spyder IDE seems a good one to implement:

#%% Section
#%%% Subsection
#%%%% Subsubsection
And so on

(2) Since VScode is providing native conversion from .py files to notebooks (.ipynb), it would be nice to have a syntax that allows the user to go back and forth between .py and .ipynb maintaining code sections, markdown sections and TOC intact.

EDIT (2023) another suggestion:

(3) Assign keyboard shortcuts to go to the previous / next code cell.

[brettcannon]

Thank you to everyone who upvoted this issue! Since the community showed interest in this feature request we will leave this issue open as something to consider implementing at some point in the future.

We do encourage people to continue 👍 this issue as it helps us prioritize our work based on what the community seems to want the most.

[ChuandongXie]

So has the hierarchical section system mentioned by @brettcannon @GitHunter0 already been introduced into VS Code? I try to find this feature but it seems haven't yet.

[brettcannon]

@ChuandongXie nothing specific from our extension has been introduced (although there may be some other extension that provides the feature). If/when we work on this we will post an update to this issue accordingly.

[starball5]

microsoft/vscode-jupyter#1964 is actually a duplicate of this and not of microsoft/vscode-jupyter#1348.

Related on Stack Overflow: In Python editors in VS Code, can I get code cells (#%%) as top hierarchy in the Outline View?

Related on r/vscode: https://www.reddit.com/r/vscode/comments/17599bc/a_way_to_get_code_cells_in_the_outline_panel/

[LiuWenJia-ops]

A feature that is very important to me! I often write lines of code as drafts, before I officially code.

[wilsonchen719]

Please implement the feature. Too important!

[chenweifelix]

I'd like to resurface this request. As a user of both R and Python, I found it very inconvenient that in .py file, I can't mark sections and navigate within my code as I do in .R within vscode. Please help implement this feature, as I believe many other R and python users would benefit from it. Plus, it would also help those considering switching from other python IDE to vscode, as mentioned in the previous comment.

[kebuAAA]

With the March 2024 (version 1.88) update releasing, the Minimap section headers may be an alternative. I have to admit that this feature is a bit of a departure from adding toc considering that it doesn't offer multiple levels of titles.

[zouter]

For those still looking for this: I found the extension regexpOutline extension really works well to implement this.
Here's the "headerRulesEachExt" setting if you are using markdown headers:
[{"ext": ".py","rules": [{"level": 1,"format": "^# #(.+)$","nameIdx": 1,"detail": "H1"},{"level": 2,"format": "^# ##(.+)$","nameIdx": 1,"detail": "H2"},{"level": 3,"format": "^# ###(.+)$","nameIdx": 1,"detail": "H3"}]}]

As an added bonus, symbols are also registered you use Ctrl+P -> @header to find the headers using just your keyboard.

[peekxc]

[{"ext": ".py","rules": [{"level": 1,"format": "^# #(.+)$","nameIdx": 1,"detail": "H1"},{"level": 2,"format": "^# ##(.+)$","nameIdx": 1,"detail": "H2"},{"level": 3,"format": "^# ###(.+)$","nameIdx": 1,"detail": "H3"}]}]

@zouter I'm unable to get this to work, though I think it's a problem with the extension. What does this look like exactly in your settings.json?

[zouter]

[{"ext": ".py","rules": [{"level": 1,"format": "^# #(.+)$","nameIdx": 1,"detail": "H1"},{"level": 2,"format": "^# ##(.+)$","nameIdx": 1,"detail": "H2"},{"level": 3,"format": "^# ###(.+)$","nameIdx": 1,"detail": "H3"}]}]

@zouter I'm unable to get this to work, though I think it's a problem with the extension. What does this look like exactly in your settings.json?

@peekxc Might be that you need to escape. This is how the settings.json line looks like:
"regexpOutline.headerRulesEachExt": "[{\"ext\": \".py\",\"rules\": [{\"level\": 1,\"format\": \"^# # (.+)$\",\"nameIdx\": 1,\"detail\": \"H1\"},{\"level\": 2,\"format\": \"^# ## (.+)$\",\"nameIdx\": 1,\"detail\": \"H2\"},{\"level\": 3,\"format\": \"^# ### (.+)$\",\"nameIdx\": 1,\"detail\": \"H3\"},{\"level\": 4,\"format\": \"^# #### (.+)$\",\"nameIdx\": 1,\"detail\": \"H4\"}]}]",