TOC for .py files with percent markup

Stav (@syagev)

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 Stav (@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.

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.

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.

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.

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.

Brett Cannon (@brettcannon)

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

Chuandong Xie (@ChuandongXie)

Chuandong Xie (@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.

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/

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

Please implement the feature. Too important!

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.

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.

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.

Wouter Saelens (@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"}]}]

Wouter Saelens (@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?

Wouter Saelens (@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"}]}]

Wouter Saelens (@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?

Matt Piekenbrock (@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\"}]}]",

For anyone wanting to replicate the Spyder cell header # %% and subcell header #### for Python files, paste the following into the Regexp Outline: Header Rules Each Ext Setting (not the JSON):

[ { "ext": ".py", "bullets": ["# %%", "####"] } ]

Wouter Saelens (@zouter)

Thanks for the community share the RregexpOutline tool and the detailed instruction. I use the formatting json setting Wouter Saelens (@zouter) suggested and works great for me. Yet too much click (when you want to see your code TOC, you have to click the Regexp Outline menu)

Still, I think this a very desired functionality deserve to be as default in this IDE, especially in the data sci / quantitative / analytics (no matter how you call us) community.
I would loooooove to have the ToC in the sidebar, I don't care about the minimap at all.

Navigation Menu

Repository navigation

TOC for .py files with percent markup #17218

Discussed in #15990

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

TOC for .py files with percent markup #17218

Description

Discussed in #15990

Activity

brettcannon commented on Sep 1, 2021

GitHunter0 commented on Sep 10, 2021

GitHunter0 commented on Sep 30, 2021

brettcannon commented on Nov 1, 2021

ChuandongXie commented on Apr 12, 2022

brettcannon commented on Apr 12, 2022

starball5 commented on Oct 11, 2023

LiuWenJia-ops commented on Nov 8, 2023

wilsonchen719 commented on Dec 14, 2023

chenweifelix commented on Apr 23, 2024

kebuAAA commented on Apr 23, 2024

zouter commented on Jun 5, 2024

peekxc commented on Jun 10, 2024

zouter commented on Jun 12, 2024

dbishel commented on Jan 9, 2025

yhsong1013 commented on May 1, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions