Sections in R scripts don't appear in Outline view

[abduazizR]

So in Rstudio, I can type ctrl+shift+R to put sections in my R script so I can track my work. Is this feature available for Positron? For R and Python?

[jmcphers]

Yes it is! Enable the RStudio keymap:

Then you'll get an "Insert Section" command binding to Ctrl + Shift + R:

It works just like RStudio's command of the same name.

There's no direct equivalent in Python, but there's something very similar for grouping code into sections; if you start a comment with #%% then Positron will recognize it as a "cell" (the same is available for R with the #+ comment).

[abduazizR]

Thanks for the response. For R, I can't see the outlines of the sections in the editor so I can navigate between them.

[jmcphers]

You're right, things like functions show up but sections don't.

That's something we should fix. I'm going to update the title of the issue. Thanks for reporting!

[rjake]

Just to highlight this request a bit further, my outlines in RStudio made heavy use of emoji and that made it very easy to navigate. I'm missing it quite a bit in Positron

```{r read-pins}
# raw data ----
## ☁ board ----
board <- board_connect()

## 📌 all_deps ----
all_deps <- pin_read(board, "my-table")
```

And for anyone curious, this is my legend

🔳 = card            👀 = observe
⏺ = constant        👉 = output
⚙  = function        💫 = reactive, starts 'r_'
💲  = input widget    

[renatovargas]

Not an issue, but a shameless request related to this. For Quarto documents (.qmd), RStudio shows only headings and subheadings in the outline, like you can see below on the left. Positron, on the other hand, shows headings, subheadings and (code cell) like you can see on the right. Now this looks great for defined code chunk listings that are named for cross refs, but very crowded for the rest of unnamed code chunks.

I am aware that you can click on "collapse all" like below, but that will collapse to first level headings only and you lose some ability to quickly navigate the document, especially in this case, where you go back and forth, perhaps trying out different elasticities in a very specific subsection to see poverty results at the end or going back to see how you set something up. I am aware also that you can individually open up each heading.

Now, I'm not saying to get rid of "(code cell)", because it encourages you to name your chunks, but I would appreciate it if there was perhaps a "toggle code cells" option, independent from collapse/expand for the Outline panel, so that you could limit it to headings and subheadings in Rmd, qmd's and other document type files. Thank you.

[juliasilge]

@renatovargas That would be a request for the Quarto VS Code extension, maybe added to this issue. Positron doesn't control what is provided there, but rather than Quarto VS Code extension.

[renatovargas]

@renatovargas That would be a request for the Quarto VS Code extension, maybe added to this issue. Positron doesn't control what is provided there, but rather than Quarto VS Code extension.

Got it, I'll move it there, thank you.

[juliasilge]

When we add support for sections in the outline view (LSP provides document symbols), let's also provide folding ranges. Discussed a little bit in #4174.

[gadenbuie]

+1 to supporting both structural comments and folding ranges!

One way that structural comments in Positron could be improved over RStudio's behavior would be to introduce a notion of hierarchy in the comments. As hinted at in @rjake's comment above, R developers currently go through some odd contortions to create (the appearance of) nested sections. It'd be very helpful if we could support nested comments directly.

Also drawing from @rjake's comment, I like the idea of using leading hashes to indicate the "level" of the section heading and trailing characters to activate the section comment behavior. For example:

# UI --------------------------------------------------------------------------

## Main Content ####

### Sidebar ----
### Inputs ----
### Cards ----

## Page Two ####

# Server ----------------------------------------------------------------------

would translate to

• UI
  • Main Content
    • Sidebar
    • Inputs
    • Cards
  • Page Two
• Server

Where the leading hashes indicate level 1 (#), level 2 (##) and level 3 (###) sections. The trailing characters – simply 4+ ---- or #### characters – activate the comment as a section divider.

[gadenbuie]

This comment is just to link to https://github.com/posit-dev/positron/issues/1427 and a note to say it's easy to miss that Positron even has an outline view.

[davidrsch]

I want to add that code cells does not appear neither in the outline view, which made me think that outline should be configurable by the user:

• Set which leading and trailing characters use to consider a comment as a header for different file extensions. This could make it easier to scale this feature for other languages. In addition regarding to headers configuration I think would be a good idea to add something like a closing section in case user wants to define objects outside a section.
• Set how many headers to include in outline.
• Set if code chunks should be included or not in outline.

[kv9898]

I note that the vscode-R extension (https://github.com/REditorSupport/vscode-R) supports the comment section formating. Hope that helps and am really looking forward to this functionality.

[lionel-]

Partially addressed by @kv9898 in https://github.com/posit-dev/ark/pull/571. The sections will now appear in the outline. Thanks for the contribution!

Keeping the issue open as this needs more work to support nested sections in the outline which currently are displayed flat.

[jmcphers]

Updating title

[julianmatthewman]

Thanks for adding this feature! Would it be possible to add support for this within lists? For example, the code below shows the sections in the outline view within the function but not within the list. RStudio shows sections within lists, and this is useful, e.g., when creating long pipelines with the targets package.

funct <- function(x) {
  # Section 1 ----
  x
  # Section 2 ----
  x+1
}

list(
  # Section 1 ----
  1,
  # Section 2 ----
  2
)

[kv9898]

Thanks for adding this feature! Would it be possible to add support for this within lists? For example, the code below shows the sections in the outline view within the function but not within the list. RStudio shows sections within lists, and this is useful, e.g., when creating long pipelines with the targets package.

funct <- function(x) {
  # Section 1 ----
  x
  # Section 2 ----
  x+1
}

list(
  # Section 1 ----
  1,
  # Section 2 ----
  2
)

You are welcome, @julianmatthewman! Aha, I thought it would be an easy one and tried to mimic our detection of functions and it turned out that things are not as easy. I believe that list is not currently one of the existing node types and including list involves changes to the treesitter. I believe @DavisVaughan is the expert on this!

In the meantime, we are trying to add the nested outline feature (https://github.com/posit-dev/ark/pull/593). This involves a lot of changes to the existing code and maybe it is a better time to include the list feature after the everything gets sorted.

[weverthonmachado]

Thanks for the feature!

Some sequences of characters seem to break the section outline. I often use something like this as section divider:

#=====================================
# Section ----
#=====================================

This makes all section titles disappear. So this works fine:

# Section 1 ----

# Section 2 ----

But adding #==== or ##### anywhere in the document breaks the outline. The problem seems to be with # followed by at least four = or # and no space + character afterwards. So these break the outline:

######
#=====
#=#=#

These do not:

###### a
#===== #
#=#=# 1

[kv9898]

Thanks for the feature!

Some sequences of characters seem to break the section outline. I often use something like this as section divider:

#=====================================
# Section ----
#=====================================

This makes all section titles disappear. So this works fine:

# Section 1 ----

# Section 2 ----

But adding #==== or ##### anywhere in the document breaks the outline. The problem seems to be with # followed by at least four = or # and no space + character afterwards. So these break the outline:

######
#=====
#=#=#

These do not:

###### a
#===== #
#=#=# 1

Thanks for the detailed description, @weverthonmachado ! I actually filed this problem at #5036 (the description is not as detailed as yours). The problem is already fixed by https://github.com/posit-dev/ark/pull/590. However, you may need to wait until the next ark/positron release. If you are impatient, you can build the development version of ark from source by following the instruction here: https://github.com/posit-dev/ark/blob/main/BUILDING.md

If you trust me, you can use my custom release version of ark (https://github.com/kv9898/ark/releases/tag/0.1.145.1) which fixes this bug. You are also welcome to try the experimental version which supports the nested sections (https://github.com/kv9898/ark/releases/tag/0.1.145.2). To use either of the custom releases, replace the binary in Positron\resources\app\extensions\positron-r\resources\ark with the new version. Remember to keep a copy of the old ark just in case something goes wrong.

[weverthonmachado]

Thanks @kv9898, that's great!

[lionel-]

Now ready for verification thanks to @kv9898!

QA notes: We now support markdown-like sections in R comments. They must have this form:

# title ----
# title ####

The number of leading # signs defines the nesting level of the section as in markdown. These comments can be combined with the other existing ways of creating outline nodes, in particular assignments and function definitions:

# title0 ----
a <- 1 

## title1 ----
foo <- function() {
  # title2 ----
  b <- 2
}

A tricky part of the implementation was to "pop" section nodes when going from a more nested to less nested section:

# foo ----
### child of foo ----
#### child of bar ----
## child of foo ----

We have unit tests for this functionality on the Ark side.

[kv9898]

@lionel- Thanks for the summary! I want to add that trailing =s are also supported:

# title ====

You can also have more than four trailing signs:

# title -----
# title ######
# title =======

[midleman]

Verified Fixed

Positron Version(s) : 2024.11.0 - 129 OS Version(s) : MacOS

Test scenario(s)

Confirmed nested sections in R scripts display in outline as expected.

Link(s) to TestRail test cases run or created:

[kv9898]

@midleman Thank you for the testing. However, ideally the code above should (and it does on my Windows and Mac devices) render an outline like this:

[midleman]

@kv9898 you are correct! my apologies, I took a screenshot from the wrong window. 😅

[abduazizR]

Is there a way to add hierarchy in the sections. I can see this with titles introduced inside functions but not elsewhere. In Rstudio, you can see there is indentation here which does not exist in Positron

[kv9898]

@abduazizR Is this the hierarchy you are referring to?

[abduazizR]

Exactly For some reason, it does not work with me

These are Positron details

Positron Version: 2024.11.0 (Universal) build 116 Code - OSS Version: 1.93.0 Commit: 8b1688ababfa228db515a739050c466f3bb3089f Date: 2024-10-28T02:50:56.075Z Electron: 30.4.0 Chromium: 124.0.6367.243 Node.js: 20.15.1 V8: 12.4.254.20-electron.0 OS: Darwin arm64 24.1.0

[kv9898]

@abduazizR Oh, this is because this feature has not been incorportated in the latest pre-release. You can wait for the next pre-release (which I think is coming out today or tomorrow) or manually downloading the latest ark and replace the existing one in extensions/positron-r to use this functionality. You can download ark from posit-dev/ark, which has this nested outline feature but not the folding feature, or from my fork, which has both (I'm using my own fork).