From f4ba2c15f9d990f062dbebd959aa4f726822df56 Mon Sep 17 00:00:00 2001 From: Davis Vaughan Date: Mon, 20 Jan 2025 11:50:04 -0500 Subject: [PATCH] Rework website to be easier to navigate --- README.md | 35 ++------ docs-old/{release.md => developer.md} | 27 +++++- docs/_quarto.yml | 14 ++-- docs/{installation.qmd => cli.qmd} | 16 ++-- docs/editor-rstudio.qmd | 45 ++++++++++ docs/editor-vscode.qmd | 73 ++++++++++++++++ docs/editors.qmd | 115 ++------------------------ docs/index.qmd | 11 ++- editors/code/README.md | 2 +- 9 files changed, 174 insertions(+), 164 deletions(-) rename docs-old/{release.md => developer.md} (68%) rename docs/{installation.qmd => cli.qmd} (87%) create mode 100644 docs/editor-rstudio.qmd create mode 100644 docs/editor-vscode.qmd diff --git a/README.md b/README.md index 35e5c22c..923e8149 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,13 @@ Air [![Actions status](https://github.com/posit-dev/air/actions/workflows/test.yml/badge.svg)](https://github.com/posit-dev/air/actions) > [!NOTE] -> air is currently in alpha. Expect breaking changes both in the API and in formatting results. +> Air is currently in alpha. Expect breaking changes both in the API and in formatting results. We also recommend that you use a version control system like git so you can easily see the changes that Air makes. An R formatter and language server, written in Rust. # Installation -Install air using our standalone installers. +Air is usable both as a command line tool and as a language server inside your favorite code editors. If you'd like to use Air within a code editor, we recommend reading our [editors guide](https://posit-dev.github.io/air/editors.html). If you'd just like to use Air from the command line, you can install Air using our standalone installers. On macOS and Linux: @@ -31,35 +31,10 @@ curl -LsSf https://github.com/posit-dev/air/releases/download/0.1.1/air-installe powershell -c "irm https://github.com/posit-dev/air/releases/download/0.1.1/air-installer.ps1 | iex" ``` -The installer scripts will automatically add air to your `PATH`. The very first time you install air, you'll need to restart your shell for the `PATH` modifications to be applied. +The installer scripts will automatically add Air to your `PATH`. The very first time you install Air, you'll need to restart your shell for the `PATH` modifications to be applied. # Acknowledgements and inspiration -air draws inspiration from many sources including [roslyn](https://github.com/dotnet/roslyn), [swift](https://github.com/swiftlang/swift), [rust-analyzer](https://github.com/rust-lang/rust-analyzer), [prettier](https://github.com/prettier/prettier), [biome](https://github.com/biomejs/biome), and [ruff](https://github.com/astral-sh/ruff). These are all excellent tools that provide either formatters, language servers, or both, all of which have influenced design decisions in air. +Air draws inspiration from many sources including [rust-analyzer](https://github.com/rust-lang/rust-analyzer), [prettier](https://github.com/prettier/prettier), [biome](https://github.com/biomejs/biome), and [ruff](https://github.com/astral-sh/ruff). These are all excellent tools that provide either formatters, language servers, or both, all of which have influenced design decisions in Air. -We are particularly thankful to [biome](https://github.com/biomejs/biome), as air is built on top of their language agnostic tooling for both building a [rowan](https://github.com/rust-analyzer/rowan) syntax tree and implementing a formatter. Biome is an open source project maintained by community members, please consider [sponsoring them](https://github.com/sponsors/biomejs#sponsors). - -# Developer notes - -Install the dev version of the air cli with: - -```sh -cargo install --path crates/air --debug -``` - -This installs it to `~/.cargo/bin` (which must be on your `PATH`), and can be removed with `cargo uninstall air`. - -Install the dev version of the VS Code extension: - -```sh -# The first time -npm install --global vsce - -# Install for Positron -cd editors/code && rm -rf *.vsix && vsce package && positron --install-extension *.vsix - -# Install for VS Code -cd editors/code && rm -rf *.vsix && vsce package && code --install-extension *.vsix -``` - -The CLI tools for Positron or VS Code need to be installed on your path using the command palette command `Shell Command: Install 'code'/'positron' command in PATH`. +We are particularly thankful to [biome](https://github.com/biomejs/biome), as Air is built on top of their language agnostic tooling for both building a [rowan](https://github.com/rust-analyzer/rowan) syntax tree and implementing a formatter. Biome is an open source project maintained by community members, please consider [sponsoring them](https://github.com/sponsors/biomejs#sponsors). diff --git a/docs-old/release.md b/docs-old/developer.md similarity index 68% rename from docs-old/release.md rename to docs-old/developer.md index 5f73dee7..05a27576 100644 --- a/docs-old/release.md +++ b/docs-old/developer.md @@ -1,4 +1,4 @@ -# CLI +# Release The release process of the air cli has some manual steps. One complication is that for each release of the CLI binary, we create a new release of the extension as this is our primary way of distributing Air. @@ -35,3 +35,28 @@ When you want to cut a release: It runs on `workflow_dispatch`, and automatically pulls in the latest release binary of Air from the binary release workflow above. There is no need to bump to an intermediate "dev version" after a release. + +# Development installation + +Install the dev version of the Air cli with: + +```sh +cargo install --path crates/air --debug +``` + +This installs it to `~/.cargo/bin` (which must be on your `PATH`), and can be removed with `cargo uninstall air`. + +Install the dev version of the VS Code extension: + +```sh +# The first time +npm install --global vsce + +# Install for Positron +cd editors/code && rm -rf *.vsix && vsce package && positron --install-extension *.vsix + +# Install for VS Code +cd editors/code && rm -rf *.vsix && vsce package && code --install-extension *.vsix +``` + +The CLI tools for Positron or VS Code need to be installed on your path using the command palette command `Shell Command: Install 'code'/'positron' command in PATH`. diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 44398e0f..54b854a9 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -10,20 +10,20 @@ website: style: "floating" search: true contents: - - text: "Overview" + - text: "Air" href: index.qmd - - text: "Installation" - href: installation.qmd + - text: "Command line" + href: cli.qmd - - text: "Editors" + - section: "Editors" href: editors.qmd + contents: + - editor-rstudio.qmd + - editor-vscode.qmd - text: "Configuration" href: configuration.qmd - - - text: "Formatter" - href: formatter.qmd margin-header: | Logo diff --git a/docs/installation.qmd b/docs/cli.qmd similarity index 87% rename from docs/installation.qmd rename to docs/cli.qmd index 67a081e1..38fc1ce1 100644 --- a/docs/installation.qmd +++ b/docs/cli.qmd @@ -1,22 +1,14 @@ --- -title: "Installing Air" +title: "Command line interface" editor: markdown: wrap: sentence canonical: true --- -If you'd like to use Air at the command line, you can use one of our standalone installers. - -```{=html} - -``` +# Installation -To install Air as a command line tool: +If you'd like to use Air at the command line, you can use one of our standalone installers. On macOS and Linux: @@ -39,3 +31,5 @@ powershell -c "irm https://github.com/posit-dev/air/releases/download/0.1.1/air- The installer scripts will automatically add Air to your `PATH`. The very first time you install Air, for the `PATH` modifications to be applied you'll need to restart your terminal. + +Note that if you'd like to use Air inside VS Code or Positron, then the Extension for those editors comes pre-bundled with an Air binary, so there's nothing you need to do besides [download the Extension](editor-vscode.qmd). diff --git a/docs/editor-rstudio.qmd b/docs/editor-rstudio.qmd new file mode 100644 index 00000000..3ac61a07 --- /dev/null +++ b/docs/editor-rstudio.qmd @@ -0,0 +1,45 @@ +--- +title: "RStudio" +editor: + markdown: + wrap: sentence + canonical: true +--- + +RStudio does not support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), but you can still use Air as an *external formatter*. + +# Installation + +::: callout-note +## Air is currently only supported on macOS and Windows. Linux support is coming soon! +::: + +Ensure you have at least RStudio version 2024.12.0, which you can download from [here](https://posit.co/download/rstudio-desktop/). +Additionally, you'll need to install the Air [command line tool](cli.qmd). + +Open `Tools -> Global Options -> Code` and change the option to use an `External` formatter. +Then set the `Reformat command` to {`path/to/air} format`. + +The easiest way to figure out `{path/to/air}` for yourself is to run `which air` from a Terminal on Unix, and `where air` from the Command Prompt on Windows. + +![](./images/rstudio-external-formatter.png){fig-alt="Setting Air as an external formatter with Tools -> Global Options -> Code -> Formatting" fig-align="center"} + +# Features + +## Format on save + +After you've set Air as an external formatter, you can either tell RStudio to format all documents on save, or set this on a per document basis. + +To format all documents on save, open `Tools -> Global Options -> Code -> Saving` and check `Reformat documents on save`. + +![](images/rstudio-format-on-save.png){fig-alt="Setting RStudio to format all documents on save in Tools -> Global Options -> Code -> Saving" fig-align="center"} + +To format individual documents on save, open the file specific settings and check `Reformat Document on Save`. + +![](images/rstudio-reformat-document-on-save.png){fig-align="center"} + + + +## Quarto + +There is currently no way to use Air in RStudio with Quarto documents. diff --git a/docs/editor-vscode.qmd b/docs/editor-vscode.qmd new file mode 100644 index 00000000..dfdc8913 --- /dev/null +++ b/docs/editor-vscode.qmd @@ -0,0 +1,73 @@ +--- +title: "VS Code and Positron" +editor: + markdown: + wrap: sentence + canonical: true +--- + +Air provides first class support for both VS Code and Positron, which both support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). + +# Installation + +::: callout-note +## Air is currently only supported on macOS and Windows. Linux support is coming soon! +::: + +Air is available [as an Extension](https://marketplace.visualstudio.com/items?itemName=Posit.air-vscode) for both VS Code and Positron. +The extension comes pre-bundled with an Air binary, so you don't need anything else to get going! +The Air extension is hosted in the VS Code Marketplace and on OpenVSX. + +# Features + +## Format on save + +Once you have the extension installed, turn on Format on Save for R documents by opening your `settings.json` and adding: + +``` json +{ + "[r]": { + "editor.formatOnSave": true + } +} +``` + +You should now be able to simply open an R document, save it, and have the entire document formatted by Air. +You can also explicitly call the command `Format Document` if you'd like to control this manually. + + + +## Format selection + +To format a selection of code, highlight it with your cursor and run the command `Format Selection`. +Formatting a selection may *expand* that selection to find the nearest complete fragment of code that is formattable. + + + +## Quarto + +Quarto support currently only works in VS Code. +There is an [issue](https://github.com/posit-dev/air/issues/77) in VS Code itself that currently prevents it from working correctly in Positron, we will fix this in Positron soon. + +### Format on save + +To format all R code cells on save, set this in your `settings.json`: + +``` json +{ + "[quarto]": { + "editor.formatOnSave": true + }, + "[r]": { + "editor.formatOnSave": true + } +} +``` + + + +### Format cell + +When inside an R cell in a Quarto document, use the chorded key combination `Cmd+K Cmd+F` or the command `Quarto: Format Cell` to format a single cell. + + diff --git a/docs/editors.qmd b/docs/editors.qmd index 0bd06555..204ed5e4 100644 --- a/docs/editors.qmd +++ b/docs/editors.qmd @@ -1,5 +1,5 @@ --- -title: "Editor setup" +title: "Editor support" editor: markdown: wrap: sentence @@ -9,115 +9,10 @@ editor: Air provides excellent support for code editors that support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). Many do, including [Positron](https://positron.posit.co/), [VS Code](https://code.visualstudio.com/), and [Zed](https://zed.dev/). Air also provides some support for code editors that allow for external formatters, such as [RStudio](https://posit.co/products/open-source/rstudio/). +Follow one of our editor specific guides to get set up with Air in your preferred editor: -```{=html} - -``` +- [Positron](editor-vscode.qmd) -# VS Code {#vs-code} - -Our VS Code extension does not yet bundle the Air binary, so the first thing you need to do is [install the Air binary](installation.qmd). -After you install the Air binary, the extension will automatically find it. - -We don't currently have a VS Code Extension on the marketplace yet, but we do build them as artifacts on each commit. -The short-term way to install the extension is to open this link in your browser, which will download a zip folder containing the extension as a vsix file: - - - -After downloading the extension, open VS Code, navigate to the Extensions pane, and drag the vsix file into the Extensions pane and "drop" it in. -VS Code will automatically recognize it and install the extension. - -## Format on save - -Once you have the extension installed, turn on Format on Save for R documents by opening your `settings.json` and adding: - -``` json -{ - "[r]": { - "editor.formatOnSave": true - } -} -``` - -You may also want to set Air as the default formatter for R documents if you have multiple R formatters installed. -You can set that with `"editor.defaultFormatter": "Posit.air"`. - -You should now be able to simply open an R document, save it, and have the entire document formatted by Air. -You can also explicitly call the command `Format Document` if you'd like to control this manually. - - - -## Format selection - -To format a selection of code, highlight it with your cursor and run the command `Format Selection`. -Formatting a selection may *expand* that selection to find the nearest complete fragment of code that is formattable. - - - -# Positron - -Follow the instructions for [VS Code](#vs-code). - -Eventually the Air extension will be available on OpenVSX for easy use in Positron. - -# RStudio - -As of RStudio 2024.12.0, there is experimental support for an "external formatter". - -RStudio does not bundle an Air binary, so the first thing you need to do is [install the Air binary](installation.qmd). - -Open `Tools -> Global Options -> Code` and change the option to use an `External` formatter. -Then set the `Reformat command` to `path/to/air format`. - -The easiest way to figure out `path/to/air` for yourself is to run `which air` from a Terminal on Mac or Linux, and `where air` from the Command Prompt on Windows. - -![](./images/rstudio-external-formatter.png){fig-alt="Setting Air as an external formatter with Tools -> Global Options -> Code -> Formatting" fig-align="center"} - -## Format on save - -After you've set Air as an external formatter, you can either tell RStudio to format all documents on save, or set this on a per document basis. - -To format all documents on save, open `Tools -> Global Options -> Code -> Saving` and check `Reformat documents on save`. - -![](images/rstudio-format-on-save.png){fig-alt="Setting RStudio to format all documents on save in Tools -> Global Options -> Code -> Saving" fig-align="center"} - -To format individual documents on save, open the file specific settings and check `Reformat Document on Save`. - -![](images/rstudio-reformat-document-on-save.png){fig-align="center"} - - - -# Quarto - -Quarto support currently only works in VS Code. - -There is an [issue](https://github.com/posit-dev/air/issues/77) in VS Code itself that currently prevents it from working correctly in Positron, we will fix this in Positron soon. - -There is currently no way to use Air in RStudio with Quarto documents. - -## Format on save - -To format all R code cells on save, set this in your `settings.json`: - -``` json -{ - "[quarto]": { - "editor.formatOnSave": true - }, - "[r]": { - "editor.formatOnSave": true - } -} -``` - - - -## Format cell - -When inside an R cell in a Quarto document, use the chorded key combination `Cmd+K Cmd+F` or the command `Quarto: Format Cell` to format a single cell. - - +- [RStudio](editor-rstudio.qmd) diff --git a/docs/index.qmd b/docs/index.qmd index 5b8aad50..909130a9 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Air" editor: markdown: wrap: sentence @@ -8,6 +8,10 @@ editor: [![](https://github.com/posit-dev/air/actions/workflows/test.yml/badge.svg)](https://github.com/posit-dev/air/actions) +::: callout-note +## Air is currently in alpha. Expect breaking changes both in the API and in formatting results. We also recommend that you use a version control system like git so you can easily see the changes that Air makes. +::: + Air is an R formatter and language server, written in Rust. - Integrates with [your favorite editor](editors.qmd) with support for @@ -16,7 +20,7 @@ Air is an R formatter and language server, written in Rust. - Format selection -- Usable from the [command line](formatter.qmd) with support for +- Usable from the [command line](cli.qmd) with support for - Formatting individual files @@ -24,6 +28,5 @@ Air is an R formatter and language server, written in Rust. - `--check` mode, suitable for a git pre-commit hook or a GitHub Actions workflow -If you'd like to use Air from the command line, read our [installation guide](installation.qmd). +If you'd like to use Air from the command line, read our [installation guide](cli.qmd). If you'd like to use Air inside a code editor, read our [editors guide](editors.qmd). - diff --git a/editors/code/README.md b/editors/code/README.md index 2c42726f..5e7789d3 100644 --- a/editors/code/README.md +++ b/editors/code/README.md @@ -14,6 +14,6 @@ Once installed, Air will automatically be activated when you open an R file. To } ``` -Click [here](https://posit-dev.github.io/air/editors.html#vs-code) to learn about all of Air's features. +Click [here](https://posit-dev.github.io/air/editor-vscode.html) to learn about all of Air's features. Click [here](https://posit-dev.github.io/air/configuration.html) to learn about how Air can be configured.