Merge pull request #1684 from Gedochao/tweak-ide-docs

Improve IDE support docs

Author: Gedochao

website/docs/cookbooks/intellij-multi-bsp.md

@@ -59,7 +59,9 @@ class MyTests1 extends munit.FunSuite {
 
 ```scala title=app2/test/MyTests2.scala
 //> using lib "com.lihaoyi::utest::0.8.1"
+
 import utest.*
+
 object MessagesTests extends TestSuite {
   val tests = Tests {
     test("my test 2") {

website/docs/cookbooks/intellij-sbt-with-bsp.md

@@ -78,7 +78,7 @@ tree -a
 </ChainedSnippets>
 
 Now, let's say that at some point you decide you need to occasionally run some scripts relevant to this project. You run
-those scripts with Scala CLI and decide it'd be convenient to keep them in the same repository. 
+those scripts with Scala CLI and decide it'd be convenient to keep them in the same repository.
 
 <ChainedSnippets>
 ```bash ignore
@@ -92,6 +92,7 @@ scripts
 
 0 directories, 2 files
 ```
+
 </ChainedSnippets>
 
 However, you already import this repo as an `SBT` project, so what can you do?

website/docs/cookbooks/intellij.md

@@ -1,5 +1,5 @@
 ---
-title: Setup Scala CLI project in IDEA IntelliJ
+title: Setup a Scala CLI project in IDEA IntelliJ
 sidebar_position: 7
 ---
 
@@ -13,7 +13,7 @@ Here's a walk-through for a simple import scenario.
 
 ```scala title=src/HelloWorld.scala
 @main
-    def hello() = println("Hello, world")
+def hello() = println("Hello, world")
 ```
 
 ```scala title=test/MyTests.test.scala

website/docs/cookbooks/vscode.md

@@ -9,7 +9,7 @@ For example, here is a simple project in scala-cli which contains only one main
 
 ```scala title=HelloWorld.scala
 @main
-    def hello() = println("Hello, world")
+def hello() = println("Hello, world")
 ```
 
 ```scala title=MyTests.test.scala
@@ -43,8 +43,8 @@ and then, we launch Visual Studio Code
 code .
 ```
 
-After starting metals, you will see the `run/debug` buttons in `HelloWorld.scala` and `test/debug` in `MyTests.test.scala` (
-assuming the following directory layout).
+After starting metals, you will see the `run/debug` buttons in `HelloWorld.scala` and `test/debug`
+in `MyTests.test.scala` (assuming the following directory layout).
 
 ![layout](/img/source_layout.png)
 

website/docs/guides/ide.md

@@ -4,7 +4,9 @@ sidebar_position: 10
 ---
 
 Scala CLI currently integrates a build server using the [BSP protocol](https://build-server-protocol.github.io/).
-At this moment Scala CLI is not automatically detected by IDEs, so we need to use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from BSP protocol to generate a connection details file (`.bsp/scala-cli.json`).
+At this moment Scala CLI is not automatically detected by IDEs, so we need to
+use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from BSP protocol to
+generate a connection details file (`.bsp/scala-cli.json`).
 
 :::note
 If none of these commands were run:
@@ -14,45 +16,52 @@ If none of these commands were run:
 - `test`
 - `setup-ide`
 
-or a previously-generated connection detail file was deleted, your IDE will *not* use Scala CLI to configure your workspace.
+or a previously-generated connection detail file was deleted, your IDE will *not* use Scala CLI to configure your
+workspace. (Although there are ongoing efforts to improve that situation.)
 
 In this case, just run one of the commands above to recreate the connection details file.
 :::
 
 Since Scala CLI has a command-line-first approach, this is reflected in its IDE integration.
-By default, Scala CLI stores options passed to the last `compile`, `run`, or `test` command, and uses those options to configure the IDE.
+By default, Scala CLI stores options passed to the last `compile`, `run`, or `test` command, and uses those options to
+configure the IDE.
 
-For more control we also expose the [`setup-ide` command](../commands/setup-ide.md), which lets you fine-tune the options that are passed to the IDE.
+For more control we also expose the [`setup-ide` command](../commands/setup-ide.md), which lets you fine-tune the
+options that are passed to the IDE.
 
 But note that once `setup-ide` is used, Scala CLI does not update the configuration based on latest command.
-To enable automatic updates again, remove the `.bsp` directory and run `compile`, `run`, or `test` to recreate the connection details file.
-
-<!-- TODO: Does this belong here? Is it related to IDEs? -->
-For now non-local sources are supported. What are non-local sources? Gists, URLs or piped sources.
+To enable automatic updates again, remove the `.bsp` directory and run `compile`, `run`, or `test` to recreate the
+connection details file.
 
+## Specific IDEs supporting Scala CLI
 
 Scala CLI has been tested with two main Scala IDEs:
- - [Metals](https://scalameta.org/metals/), which is an LSP server for Scala, and is used with [Visual Studio Code](https://code.visualstudio.com/), [Vim](https://www.vim.org/) and many other editors
- - [IntelliJ IDEA](https://www.jetbrains.com/idea/), with the [Scala Plugin](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA?_ga=2.54176744.1963952405.1634470110-410935139.1631638301) installed
 
-In an ideal world we would replace the rest of this guide with something along the lines of, “Scala CLI works within IDEs above as you would expect.” However, mainly due to how fresh Scala CLI is, and also due to our radical approach to the project structure, using a Scala CLI project with your favourite IDE may not be as amazing as we would like. (That being said, proper IDE integration is our top priority at this moment!)
+- [Metals](https://scalameta.org/metals/), which is an LSP server for Scala, and is used
+  with [Visual Studio Code](https://code.visualstudio.com/), [Vim](https://www.vim.org/) and many other editors
+- [IntelliJ IDEA](https://www.jetbrains.com/idea/), with
+  the [Scala Plugin](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA?_ga=2.54176744.1963952405.1634470110-410935139.1631638301)
+  installed
+
+In an ideal world we would replace the rest of this guide with something along the lines of, “Scala CLI works within
+IDEs above as you would expect.” However, mainly due to how fresh Scala CLI is, and also due to our radical approach to
+the project structure, using a Scala CLI project with your favourite IDE may not be as amazing as we would like. (That
+being said, proper IDE integration is our top priority at this moment!)
 
-## Metals
+### VS Code with Metals
 
-Once Metals picks up the project structure that’s created by Scala CLI, basic features like navigation, diagnostics, and code completion should work.
-Reloading the workspace on project structure changes is currently experimental and should work for most scenarios, we are working on improving its stability.
-For some cases it may still be necessary to restart the build server manually.
-(Closing & reopening the project should also be sufficient.)
+Check the cookbook on [how to set up a Scala CLI project in VSCode with Metals](../cookbooks/vscode.md).
 
-## IntelliJ
+### IntelliJ
 
-Here are a few notes related to IntelliJ support:
-- IntelliJ currently does not automatically pick up changes in the project structure, so any change in dependencies, compiler options, etc., need to be manually reloaded.
-- Similarly to Metals, reloading the workspace on project structure changes is currently experimental and should work for most scenarios.
-  We are working on improving its stability. For some cases it may still be necessary to restart the build server manually.
-  (Closing & reopening the project should also be sufficient.)
+Cookbooks on how to work with IntelliJ:
+
+- [set up a simple Scala CLI project in IDEA IntelliJ](../cookbooks/intellij.md)
+- [set up a Scala CLI project in IntelliJ alongside an existing SBT project](../cookbooks/intellij-sbt-with-bsp.md)
+- [set up multiple Scala CLI projects in IDEA IntelliJ as separate modules](../cookbooks/intellij-multi-bsp.md)
 
 ## Directories vs single files when working with an IDE
+
 When working with Scala CLI in an IDE, it is generally suggested to use directories rather than single files.
 
 ```shell
@@ -66,9 +75,11 @@ everything within a given project root directory is at least implicitly treated
 a part of the project (and probably shown as part of your project structure).
 
 This means that when you pass just a single source file to Scala CLI like this:
+
 ```shell
 scala-cli setup-ide some-directory/A.scala
 ```
+
 If you open its surrounding directory as a project, any other files present in that directory will be visible
 in your IDE project's structure, but they will not be included in your builds.
 
@@ -77,16 +88,32 @@ alongside the previously configured `some-directory/A.scala`, it is probably not
 to create the file within the same directory in your IDE.
 
 What you need to do instead is add it to your build with Scala CLI from the command line:
+
 ```shell
 scala-cli setup-ide some-directory/A.scala some-directory/B.scala
 ```
+
 There, now both `A.scala` and `B.scala` should be included in your builds when the IDE picks up the new structure.
 
 Still, if you want to add/remove files like this a lot while working in an IDE,
 it may be a lot simpler to work on the whole directory instead:
+
 ```shell
 cd some-directory
 scala-cli setup-ide .
 ```
+
 That way all the contents of `some-directory` will be treated as a part of the project as you go,
 without the need to jump into the command line whenever you create a new file.
+
+## Remote and virtual inputs
+
+Do note that IDEs do not yet support working with Scala CLI's remote and virtual inputs. That includes:
+
+- [piped sources](./piping.md),
+- URLs and [GitHub gists](../cookbooks/gists.md),
+- [code snippets](./snippets.md).
+
+Beyond that, IDE support for some non-standard (like `.c` and `.h` resources used
+with [Scala Native](./scala-native.md)) and experimental inputs (like i.e. [`.md` sources](./markdown.md)) may not yet
+be on par with on-disk Scala and Java source files.