Outline view: Support nested sections in R scripts

[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    

[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 #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 posit-dev/ark#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 (posit-dev/ark#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 posit-dev/ark#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. 😅