You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add more docs around migration from RStudio (#116)
* And so it begins. Especially the overview.
* Add some links
* Rename files to match convention from vscode migration guide
* Work on overview
* New topic about user interface
* Talk about keybindings
* Guide on formatting R code and R snippets
* Mention command palette's importance in the overview
* New topic on navigation
* Scaffold the settings and extensions page
* Stub for "workspace"
* Polishing based on seeing a full preview
* Apply suggestions from code review
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Fix some issues raised by Vale
* Is it necessary to say that "R" is allowed in headings?
* Use suggested rewording
* Add additional page to yaml
* Apply suggestions from code review
Co-authored-by: Davis Vaughan <davis@posit.co>
* Add "Command Palette" to accept list
* Now we require "Command Palette" everywhere
* Update page on settings & extensions
* Make vale happy
* Update keyboard shortcut pages
* Update page on R code
* Add links, fix headers
* Update docs on workspace and `.Rproj`
* Update R shortcuts
* Rearrange a bit, for a better landing page at the `/migrate-rstudio` slug
* Add callouts for in-product migration guides
* I guess I am doing these one at a time 🙄
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* I guess I am doing these one at a time 🙄
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* I guess I am doing these one at a time 🙄
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Get this fix manually 🙄
* Add GH link for import dataset widget
* Clarify sentence on main RStudio landing page
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Davis Vaughan <davis@posit.co>
* RStudio has deeper support for Sweave and R Markdown compared to our targeted focus on Quarto in Positron, although Positron does support rendering R Markdown documents as well.
40
40
* Positron does not have inline output for source `.qmd` or `.Rmd` documents at this time, and Quarto or R Markdown documents will make use of the console and plot pane for execution/output. However, we are actively enhancing our Positron-native notebook UI that will provide inline outputs for R or Python sessions. Separately, we are also actively working on improving Quarto's Visual Editor to improve the authoring experience for Quarto.
41
41
* RStudio is extensible only via RStudio add-ins, and while Positron supports some of the same, existing RStudio add-ins, not all are supported. Rather than doubling down on the more limited RStudio add-in capabilities for novel integrations, we suggest exploring [extension development and our Positron API endpoints](extension-development.qmd).
42
-
* We do _not_ plan to have a `.Rproj` equivalent for Positron (e.g. a `.positronproj`), but rather Positron can open and treat any folder as a "project" or workspace. We still suggest project-oriented workflows, and for more context, please see: [Migrating from RStudio: The Rproj File](rstudio-rproj-file.qmd).
42
+
* We do _not_ plan to have a `.Rproj` equivalent for Positron (e.g. a `.positronproj`), but rather Positron can open and treat any folder as a "project" or workspace. We still suggest project-oriented workflows, and for more context, please see: [Migrating from RStudio: The Rproj File](migrate-rstudio-rproj.qmd).
43
43
44
44
### I'm coming from RStudio, and Positron's keybindings are too different
45
45
46
-
* Check out the [RStudio Keymap](keyboard-shortcuts.qmd#rstudio-keymap) section of our documentation.
46
+
* Check out the [RStudio Keybindings](migrate-rstudio-keybindings.qmd) section of our documentation.
47
47
* To opt in to these RStudio-like keybindings, enable the [`workbench.keybindings.rstudioKeybindings` setting](positron://settings/workbench.keybindings.rstudioKeybindings).
48
48
49
49
### How can I use Positron in an educational setting?
Copy file name to clipboardExpand all lines: git.qmd
+1Lines changed: 1 addition & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,7 @@ Positron provides a 3-way merge editor to help you resolve conflicts by choosing
91
91
**Learn more:**[Merge conflicts in VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview#_merge-conflicts)
92
92
93
93
## Integration with Git platforms
94
+
94
95
Positron includes the [GitHub](https://open-vsx.org/extension/vscode/github) and [GitHub Pull Requests and Issues](https://open-vsx.org/extension/GitHub/vscode-pull-request-github) extensions out of the box, which let you manage GitHub repositories, issues, and PRs directly from within Positron. You can learn more about the extensions that Positron automatically installs for you on the [Extensions](extensions.qmd#bootstrapped-extensions) page.
95
96
96
97
Other platforms are not integrated by default, but similar features are available after installing extensions like [GitLab Workflow](https://open-vsx.org/extension/GitLab/gitlab-workflow) or [Atlassian: Jira & Bitbucket](https://open-vsx.org/extension/atlassian/atlascode). You can search in the [Extensions pane](extensions.qmd#accessing-extensions) to find other extensions for the Git platform you use.
| {{< kbd mac=Command-Shift-L win=Ctrl-Shift-L linux=Ctrl-Shift-L >}} | Load the current R package, if any, with `devtools::load_all()`|
31
33
| {{< kbd mac=Command-Shift-B win=Ctrl-Shift-B linux=Ctrl-Shift-B >}} | Build and install the current R package, if any |
32
34
| {{< kbd mac=Command-Shift-T win=Ctrl-Shift-T linux=Ctrl-Shift-T >}} | Test the current R package, if any |
33
35
| {{< kbd mac=Command-Shift-E win=Ctrl-Shift-E linux=Ctrl-Shift-E >}} | Check the current R package, if any |
34
36
| {{< kbd mac=Command-Shift-D win=Ctrl-Shift-D linux=Ctrl-Shift-D >}} | Document the current R package, if any |
35
37
36
-
## RStudio keybindings
37
-
38
-
If you'd prefer to use RStudio keybindings, see [our instructions](rstudio-keybindings.qmd) on how to enable them for Positron.
38
+
:::{.callout-note}
39
+
If you'd prefer to use RStudio keybindings, learn [how to enable them](migrate-rstudio-keybindings.qmd) in Positron.
40
+
:::
39
41
40
42
## Custom shortcuts
41
43
42
-
Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`.
44
+
Because Positron is built on top of VS Code, you can use [its infrastructure for defining custom keybindings](https://code.visualstudio.com/docs/getstarted/keybindings). You can use this infrastructure with any Positron-specific commands, such as `workbench.action.executeCode.console` or `workbench.action.executeCode.silently`.
43
45
44
46
As a specific example, you could add the following to your user `keybindings.json` (access this file from the Command Palette with *Open Keyboard Shortcuts (JSON)*) to make a keyboard shortcut to create a reprex from your current selection:
45
47
@@ -56,6 +58,15 @@ As a specific example, you could add the following to your user `keybindings.jso
56
58
}
57
59
```
58
60
61
+
## Troubleshooting
62
+
63
+
If you are puzzled by the behaviour of a keyboard shortcut, here are two issues to consider:
64
+
65
+
***Context:** Many keyboard shortcuts are only enabled in certain contexts, such as when editing code or when working in an R package. Consider if you might be invoking the shortcut in an unexpected and unsupported context.
66
+
***Conflicts:** A keyboard shortcut can have multiple associations across different situations or extensions. When a shortcut is associated with more than one command, a priority system determines which command wins and the result might not be what you expect.
67
+
68
+
The command _Preferences: Open Keyboard Shortcuts_ opens [an interface](https://code.visualstudio.com/docs/configure/keybindings) that is a great way to investigate keyboard shortcut mysteries.
69
+
59
70
Be aware that Positron's integrated terminal can [intercept some keyboard shortcuts](https://code.visualstudio.com/docs/terminal/advanced#_keyboard-shortcuts-and-the-shell). You can set up a keybinding to skip the shell by specifying its command in the [`terminal.integrated.commandsToSkipShell` setting](positron://settings/terminal.integrated.commandsToSkipShell), either via the settings UI or by editing `settings.json`:
60
71
61
72
```json
@@ -65,4 +76,4 @@ Be aware that Positron's integrated terminal can [intercept some keyboard shortc
Copy file name to clipboardExpand all lines: migrate-rstudio-code.qmd
+85-7Lines changed: 85 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,85 @@
1
1
---
2
-
title: "Snippets for R"
2
+
title: "Writing R code"
3
+
aliases:
4
+
- r-snippets.qmd
3
5
---
4
6
7
+
Writing R code in Positron should feel quite familiar to RStudio users.
8
+
However two aspects of the workflow might feel a bit different:
9
+
10
+
*[Formatting via Air](#formatting-r-code-with-air)
11
+
*[Snippets](#r-snippets), both built-in and custom
12
+
13
+
## Formatting R code with Air
14
+
15
+
Positron can format R code with [Air](https://posit-dev.github.io/air/), a new R formatter whose creation was largely motivated by Positron.
16
+
17
+
A formatter takes charge of the layout of your R code, which refers to whitespace, newlines, indentation, and the like.
18
+
The goal is to enforce a set of style conventions that enhance readability and robustness.
19
+
Air shares properties with other modern formatters and linters, such as Ruff for Python:
20
+
21
+
* It's highly opinionated and offers relatively few options for customization.
22
+
* It's written in Rust, which makes it extremely fast.
23
+
24
+
### How do I install Air?
25
+
26
+
Air is a command line tool which automatically ships with Positron.
27
+
Most Positron users do not need to do anything intentional to install Air or to keep it up-to-date.
28
+
29
+
Under the hood, Air is packaged in a VS Code extension, included in Positron as a [bootstrapped extension](extensions.qmd#bootstrapped-extensions) that is installed for you.
30
+
The Air extension is published on [Open VSX](https://open-vsx.org/extension/posit/air-vscode), the marketplace used by IDEs like Positron and Cursor, and also on the [Visual Studio Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode), which serves only the proprietary Microsoft builds of Visual Studio Code.
31
+
32
+
### How do I use Air?
33
+
34
+
There are various explicit and implicit gestures to run Air over your R code:
35
+
36
+
* "Format on save": formats R code every time you save a file. This is a lifestyle you must opt in to, but it is our strong recommendation that you do so. Below we give details on how to set this up.
37
+
* Formatting commands: These are explicit gestures to format specific bits of code.
38
+
-*Format Selection*
39
+
-*Format Document*
40
+
-*Quarto: Format Cell*
41
+
-*Air: Format Workspace Folder*
42
+
43
+
These are all available in the command palette.
44
+
45
+
All R code receives some basic formatting as you type, but this first pass is focused only on indentation.
46
+
A second formatting pass with Air, when you save the file or intentionally format it, produces a much better result, since Air works off of an actual syntax tree.
47
+
48
+
:::{.callout-tip}
49
+
You can use special comments to tell Air to [skip formatting specific sections of code](https://posit-dev.github.io/air/formatter.html#skip-comments), if you don't want to apply Air's strict formatting rules in a specific situation.
50
+
:::
51
+
52
+
### Opt in to "Format on save"
53
+
54
+
The easiest way to get our recommended set up is to run [`usethis::use_air()`](https://usethis.r-lib.org/dev/reference/use_air.html) (note that this currently requires the development version of usethis).
55
+
`use_air()` configures "Format on save" in the current workspace by modifying (or creating, if necessary) the `.vscode/settings.json` file.
56
+
It also creates an `air.toml` file.
57
+
58
+
VS Code and Positron let you customize settings at the user level and at the workspace level (i.e. for just the current project you are working on).
59
+
We think "Format on save" makes the most sense to configure at the workspace level:
60
+
61
+
* Workspace settings are recorded inside the workspace at `.vscode/settings.json`, allowing them to be tracked in version control. This means that all collaborators get those settings automatically when they check out the project, enforcing a common formatting style.
62
+
* User level settings apply to any workspaces that you open. This sounds nice in theory, but you might not want automatic Air formatting in older projects or in projects that you don't own. If you opt in at the user level, you'll have to turn Air off somehow in these projects or risk creating a huge number of formatting diffs, when that's probably not your intent.
63
+
64
+
Here is what `.vscode/settings.json` might look like for someone who wants their R code formatted on save, in both R scripts and Quarto documents:
65
+
66
+
```json
67
+
{
68
+
"[r]": {
69
+
"editor.formatOnSave": true,
70
+
"editor.defaultFormatter": "Posit.air-vscode"
71
+
},
72
+
"[quarto]": {
73
+
"editor.formatOnSave": true,
74
+
"editor.defaultFormatter": "quarto.quarto"
75
+
}
76
+
}
77
+
```
78
+
79
+
To learn more about using Air, read its documentation for [Positron and VS Code](https://posit-dev.github.io/air/editor-vscode.html).
80
+
81
+
## R snippets
82
+
5
83
Code snippets let you insert ready-made templates for common coding patterns.
6
84
For example, `for` is a reserved word in R that is used to create a loop.
7
85
In actual usage, `for` is always part of a larger construct:
@@ -16,15 +94,15 @@ A snippet for `for` inserts this whole skeleton, with special placeholders that
16
94
17
95
{width=700}
18
96
19
-
It is common for IDEs to provide explicit support for code snippets and this certainly holds true for RStudio and Positron.
20
-
This guide is intended to help users who have used snippets in RStudio adapt their approach for Positron, which inherits snippet behaviour from its VS Code roots.
97
+
It is common for IDEs to provide explicit support for code snippets and this certainly holds true for both RStudio and Positron.
98
+
This guide is intended to help users who have used snippets in RStudio adapt their approach for Positron, which inherits snippet behavior from its Code OSS architecture.
For our purposes, it's useful to break them into two broad classes:
@@ -37,7 +115,7 @@ Under the hood, this initializes a user-level snippet file that is pre-populated
37
115
You can then apply your desired changes, such as adding or deleting snippets.
38
116
Going forward, this user-level file powers all of your RStudio snippets, i.e. there is no combining of built-in and user-level snippets.
39
117
40
-
## Default and custom snippets in Positron
118
+
###Default and custom snippets in Positron
41
119
42
120
The completion experience in Positron arises from two components working together:
43
121
@@ -49,14 +127,14 @@ The completion experience in Positron arises from two components working togethe
49
127
50
128
This division of labor means that the completion and snippet responsibilities are a bit different in Positron than in RStudio.
51
129
52
-
### Reserved words
130
+
####Reserved words
53
131
54
132
In Positron, the completion items related to R's reserved words are built into ark.
55
133
Each reserved word can be completed on its own and, in some cases, as part of a larger snippet.
56
134
57
135
{width=700}
58
136
59
-
### Everything else
137
+
####Everything else
60
138
61
139
If you want snippets beyond those provided for R's reserved words, you'll need to configure that for yourself.
62
140
Press {{< kbd mac=Command-Shift-P win=Ctrl-Shift-P linux=Ctrl-Shift-P >}} to open the command palette and type *Snippets: Configure Snippets*.
RStudio is stable and actively supported, and there is no timeline to deprecate it.
9
+
That being said, RStudio and Positron are at very different points in their respective lifecycles, which is relevant when making decisions about adoption.
10
+
Positron is under much more active development, with a rapidly expanding set of features.
11
+
RStudio's development, on the other hand, is much more focused on bug fixes and product stability.
12
+
13
+
## Features unique to RStudio
14
+
15
+
Some features are present in RStudio, but not in Positron as of today.
16
+
Some of these features may eventually come to Positron, but if any of these are dealbreakers for you, that is a reason for you to stick with RStudio.
17
+
18
+
* Inline output in Quarto documents, i.e. a notebook-style interface for `.qmd` (or `.Rmd`) files. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5640>.
19
+
* Saving and reloading workspace state when you restart R.
20
+
* Dedicated panes and buttons for specialized tasks, such code profiling or installing or developing packages.
21
+
* History pane. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5484>.
22
+
* Data import widget. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/5515>.
23
+
* RStudio add-ins. Follow along for updates on this feature request in <https://github.com/posit-dev/positron/issues/1313>.
24
+
25
+
## Features unique to Positron
26
+
27
+
Some features are available in Positron, but not in RStudio.
28
+
If any of these features are very appealing to you, that is a reason to move some or perhaps all of your work to Positron.
29
+
30
+
* Easy access to [multiple R versions](r-installations.qmd) and [multiple concurrent R sessions](managing-interpreters.qmd).
31
+
* An [integrated AI assistant](assistant.qmd) that can "see" and, optionally, execute code in your active R (or Python) sessions, among many other capabilities.
32
+
* Python as a first-class citizen, with support for data science workflows that is on par with R.
33
+
* Support for other languages beyond R and Python, via built-in language intelligence or extensions.
34
+
* An integrated [Data Explorer](data-explorer.qmd) for dataframes in your active R (or Python) sessions and for a variety data files (CSV, Parquet, etc.).
35
+
* Extensibility via a large marketplace of 3rd party [extensions](extensions.qmd).
36
+
*[Remote sessions](remote-ssh.qmd), i.e. where the user interface is local but the compute is elsewhere.
37
+
38
+
39
+
::: {.callout-tip}
40
+
It's worth pointing out that using Positron is not an all-or-nothing decision.
41
+
It is entirely reasonable to use Positron in some projects and RStudio in others.
42
+
Likewise, within a specific project, some tasks might feel easier in Positron and others in RStudio.
43
+
There is nothing irreversible or exclusive about interacting with the files that constitute a project from one IDE versus another.
0 commit comments