docs: Add initial language settings documentation (#6957)

Brian Ginsburg created 2 years ago

This pull request implements the following documentation changes:

- [x] Copy existing language settings docs from old docs repo
- [x] Add new pages for Zig, Haskell, Gleam, Deno and PureScript
- [x] Add `rust-analyzer` target directory section to Rust language page

Release Notes:

- Added initial language settings documentation
([#4264](https://github.com/zed-industries/zed/issues/4264)).

Change summary

docs/src/languages/c.md          |  4 ++
docs/src/languages/cpp.md        |  4 ++
docs/src/languages/css.md        |  4 ++
docs/src/languages/deno.md       |  4 ++
docs/src/languages/elixir.md     | 43 ++++++++++++++++++++++++
docs/src/languages/elm.md        |  4 ++
docs/src/languages/erb.md        |  4 ++
docs/src/languages/gleam.md      |  4 ++
docs/src/languages/go.md         |  4 ++
docs/src/languages/haskell.md    |  4 ++
docs/src/languages/html.md       |  4 ++
docs/src/languages/javascript.md | 25 ++++++++++++++
docs/src/languages/json.md       |  4 ++
docs/src/languages/lua.md        |  4 ++
docs/src/languages/markdown.md   |  4 ++
docs/src/languages/php.md        |  4 ++
docs/src/languages/purescript.md |  4 ++
docs/src/languages/python.md     | 60 ++++++++++++++++++++++++++++++++++
docs/src/languages/racket.md     |  4 ++
docs/src/languages/ruby.md       | 39 ++++++++++++++++++++++
docs/src/languages/rust.md       | 24 +++++++++++++
docs/src/languages/scheme.md     |  4 ++
docs/src/languages/svelte.md     |  4 ++
docs/src/languages/toml.md       |  5 ++
docs/src/languages/tsx.md        |  4 ++
docs/src/languages/typescript.md |  4 ++
docs/src/languages/vue.md        |  4 ++
docs/src/languages/yaml.md       |  4 ++
docs/src/languages/zig.md        |  4 ++
29 files changed, 288 insertions(+)

Detailed changes

docs/src/languages/c.md

@@ -0,0 +1,4 @@
+# C
+
+- Tree Sitter: [tree-sitter-c](https://github.com/tree-sitter/tree-sitter-c)
+- Language Server: [clangd](https://github.com/clangd/clangd)

docs/src/languages/cpp.md

@@ -0,0 +1,4 @@
+# C++
+
+- Tree Sitter: [tree-sitter-cpp](https://github.com/tree-sitter/tree-sitter-cpp)
+- Language Server: [clangd](https://github.com/clangd/clangd)

docs/src/languages/css.md

@@ -0,0 +1,4 @@
+# CSS
+
+- Tree Sitter: [tree-sitter-css](https://github.com/tree-sitter/tree-sitter-css)
+- Language Server: N/A

docs/src/languages/deno.md

@@ -0,0 +1,4 @@
+# Deno
+
+- Tree Sitter: [tree-sitter-typescript](https://github.com/tree-sitter/tree-sitter-typescript)
+- Language Server: [deno](https://github.com/denoland/deno)

docs/src/languages/elixir.md

@@ -0,0 +1,43 @@
+# Elixir
+
+- Tree Sitter: [tree-sitter-elixir](https://github.com/elixir-lang/tree-sitter-elixir)
+- Language Server: [elixir-ls](https://github.com/elixir-lsp/elixir-ls)
+
+### Setting up `elixir-ls`
+
+1. Install `elixir`:
+
+```bash
+brew install elixir
+```
+
+2. Install `elixir-ls`:
+
+```bash
+brew install elixir-ls
+```
+
+3. Restart Zed
+
+{% hint style="warning" %}
+If `elixir-ls` is not running in an elixir project, check the error log via the command palette action `zed: open log`.  If you find an error message mentioning: `invalid LSP message header "Shall I install Hex? (if running non-interactively, use \"mix local.hex --force\") [Yn]`, you might need to install [`Hex`](https://hex.pm). You run `elixir-ls` from the command line and accept the prompt to install `Hex`.
+{% endhint %}
+
+### Formatting with Mix
+
+If you prefer to format your code with [Mix](https://hexdocs.pm/mix/Mix.html), use the following snippet in your `settings.json` file to configure it as an external formatter.  Formatting will occur on file save.
+
+```json
+{
+  "language_overrides": {
+    "Elixir": {
+      "format_on_save": {
+        "external": {
+          "command": "mix",
+          "arguments": ["format", "--stdin-filename", "{buffer_path}", "-"]
+        }
+      }
+    }
+  }
+}
+```

docs/src/languages/elm.md

@@ -0,0 +1,4 @@
+# Elm
+
+- Tree Sitter: [tree-sitter-elm](https://github.com/elm-tooling/tree-sitter-elm)
+- Language Server: N/A

docs/src/languages/erb.md

@@ -0,0 +1,4 @@
+# ERB
+
+- Tree Sitter: [tree-sitter-embedded-template](https://github.com/tree-sitter/tree-sitter-embedded-template)
+- Language Server: [solargraph](https://github.com/castwide/solargraph)

docs/src/languages/gleam.md

@@ -0,0 +1,4 @@
+# Gleam
+
+- Tree Sitter: [tree-sitter-gleam](https://github.com/gleam-lang/tree-sitter-gleam)
+- Language Server: [gleam](https://github.com/gleam-lang/gleam)

docs/src/languages/go.md

@@ -0,0 +1,4 @@
+# Go
+
+- Tree Sitter: [tree-sitter-go](https://github.com/tree-sitter/tree-sitter-go)
+- Language Server: [gopls](https://github.com/golang/tools/tree/master/gopls)

docs/src/languages/haskell.md

@@ -0,0 +1,4 @@
+# Haskell
+
+- Tree Sitter: [tree-sitter-haskell](https://github.com/tree-sitter/tree-sitter-haskell)
+- Language Server: [hls](https://github.com/haskell/haskell-language-server)

docs/src/languages/html.md

@@ -0,0 +1,4 @@
+# HTML
+
+- Tree Sitter: [tree-sitter-html](https://github.com/tree-sitter/tree-sitter-html)
+- Language Server: [vscode-html-language-server](https://github.com/hrsh7th/vscode-langservers-extracted)

docs/src/languages/javascript.md

@@ -0,0 +1,25 @@
+# JavaScript
+
+- Tree Sitter: [tree-sitter-javascript](https://github.com/tree-sitter/tree-sitter-javascript)
+- Language Server: [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)
+
+### Code formatting
+
+Formatting on save is enabled by default for JavaScript, using TypeScript's built-in code formatting. But many JavaScript projects use other command-line code-formatting tools, such as [Prettier](https://prettier.io/). You can use one of these tools by specifying an _external_ code formatter for JavaScript in your settings. See the [configuration](../configuration/configuring-zed.md) documentation for more information.
+
+For example, if you have Prettier installed and on your `PATH`, you can use it to format JavaScript files by adding the following to your `settings.json`:
+
+```json
+{
+  "language_overrides": {
+    "JavaScript": {
+      "format_on_save": {
+        "external": {
+          "command": "prettier",
+          "arguments": ["--stdin-filepath", "{buffer_path}"]
+        }
+      }
+    }
+  }
+}
+```

docs/src/languages/json.md

@@ -0,0 +1,4 @@
+# JSON
+
+- Tree Sitter: [tree-sitter-json](https://github.com/tree-sitter/tree-sitter-json)
+- Language Server: [json-language-server](https://github.com/zed-industries/json-language-server)

docs/src/languages/lua.md

@@ -0,0 +1,4 @@
+# Lua
+
+- Tree Sitter: [tree-sitter-lua](https://github.com/MunifTanjim/tree-sitter-lua)
+- Language Server: [lua-language-server](https://github.com/LuaLS/lua-language-server)

docs/src/languages/markdown.md

@@ -0,0 +1,4 @@
+# Markdown
+
+- Tree Sitter: [tree-sitter-markdown](https://github.com/MDeiml/tree-sitter-markdown)
+- Language Server: N/A

docs/src/languages/php.md

@@ -0,0 +1,4 @@
+# PHP
+
+- Tree Sitter: [tree-sitter-php](https://github.com/tree-sitter/tree-sitter-php)
+- Language Server: [intelephense](https://intelephense.com/)

docs/src/languages/purescript.md

@@ -0,0 +1,4 @@
+# PureScript
+
+- Tree Sitter: [tree-sitter-purescript](https://github.com/ivanmoreau/tree-sitter-purescript)
+- Language Server: [purescript](https://github.com/nwolverson/purescript-language-server)

docs/src/languages/python.md

@@ -0,0 +1,60 @@
+# Python
+
+- Tree Sitter: [tree-sitter-python](https://github.com/tree-sitter/tree-sitter-python)
+- Language Server: [pyright](https://github.com/microsoft/pyright)
+
+### Configuration
+
+The [pyright](https://github.com/microsoft/pyright) language server offers flexible configuration options specified in a JSON-formatted text configuration. By default, the file is called `pyrightconfig.json` and is located within the root directory of your project. Pyright settings can also be specified in a `[tool.pyright]` section of a `pyproject.toml` file. A `pyrightconfig.json` file always takes precedent over `pyproject.toml` if both are present.
+
+For more information, see the Pyright [configuration documentation](https://microsoft.github.io/pyright/#/configuration).
+
+### Virtual environments
+
+A python [virtual environment](https://docs.python.org/3/tutorial/venv.html) allows you to store all of a project's dependencies, including the Python interpreter and package manager, in a single directory that's isolated from any other Python projects on your computer.
+
+By default, the Pyright language server will look for Python packages in the default global locations. But you can also configure Pyright to use the packages installed in a given virtual environment.
+
+To do this, create a JSON file called `pyrightconfig.json` at the root of your project. This file must include two keys:
+
+* `venvPath`: a relative path from your project directory to any directory that _contains_ one or more virtual environment directories
+* `venv`: the name of a virtual environment directory
+
+For example, a common approach is to create a virtual environment directory called `.venv` at the root of your project directory with the following commands:
+
+```bash
+# create a virtual environment in the .venv directory
+python3 -m venv .venv
+# set up the current shell to use that virtual environment
+source .venv/bin/activate
+```
+
+Having done that, you would create a `pyrightconfig.json` with the following content:
+
+```json
+{
+  "venvPath": ".",
+  "venv": ".venv"
+}
+```
+
+### Code formatting
+
+The Pyright language server does not provide code formatting. If you want to automatically reformat your Python code when saving, you'll need to specify an _external_code formatter in your settings. See the [configuration](../configuration/configuring-zed.md) documentation for more information.
+
+A common tool for formatting python code is [Black](https://black.readthedocs.io/en/stable/). If you have Black installed globally, you can use it to format Python files by adding the following to your `settings.json`:
+
+```json
+{
+  "language_overrides": {
+    "Python": {
+      "format_on_save": {
+        "external": {
+          "command": "black",
+          "arguments": ["-"]
+        }
+      }
+    }
+  }
+}
+```

docs/src/languages/racket.md

@@ -0,0 +1,4 @@
+# Racket
+
+- Tree Sitter: [tree-sitter-racket](https://github.com/zed-industries/tree-sitter-racket)
+- Language Server: N/A

docs/src/languages/ruby.md

@@ -0,0 +1,39 @@
+# Ruby
+
+- Tree Sitter: [tree-sitter-ruby](https://github.com/tree-sitter/tree-sitter-ruby)
+- Language Server: [solargraph](https://github.com/castwide/solargraph)
+
+### Setup
+
+Zed currently doesn't install Solargraph automatically. To use Solargraph, you need to install the gem. Zed just looks for an executable called `solargraph` on your `PATH`.
+
+You can install the gem manually with the following command:
+
+```shell
+gem install solargraph
+```
+
+Alternatively, if your project uses Bundler, you can add the Solargraph gem to your `Gemfile`:
+
+```ruby
+gem 'solargraph', group: :development
+```
+
+Solargraph has formatting and diagnostics disabled by default. We can tell Zed to enable them by adding the following to your `settings.json`:
+
+```json
+{
+   "lsp": {
+      "solargraph": {
+         "initialization_options": {
+            "diagnostics": true,
+            "formatting": true
+         }
+      }
+   }
+}
+```
+
+### Configuration
+
+Solargraph reads its configuration from a file called `.solargraph.yml` in the root of your project. For more information about this file, see the [Solargraph configuration documentation](https://solargraph.org/guides/configuration).

docs/src/languages/rust.md

@@ -0,0 +1,24 @@
+# Rust
+
+- Tree Sitter: [tree-sitter-rust](https://github.com/tree-sitter/tree-sitter-rust)
+- Language Server: [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
+
+### Target directory
+
+The `rust-analyzer` target directory can be set in `initialization_options`:
+
+```json
+{
+  "lsp": {
+    "rust-analyzer": {
+      "initialization_options": {
+        "rust": {
+          "analyzerTargetDir": true
+        }
+      }
+    }
+  }
+}
+```
+
+A `true` setting will set the target directory to `target/rust-analyzer`. You can set a custom directory with a string like `"target/analyzer"` instead of `true`.

docs/src/languages/scheme.md

@@ -0,0 +1,4 @@
+# Scheme
+
+- Tree Sitter: [tree-sitter-scheme](https://github.com/6cdh/tree-sitter-scheme)
+- Language Server: N/A

docs/src/languages/svelte.md

@@ -0,0 +1,4 @@
+# Svelte
+
+- Tree Sitter: [tree-sitter-svelte](https://github.com/Himujjal/tree-sitter-svelte)
+- Language Server: [svelte](https://github.com/sveltejs/language-tools/tree/master/packages/language-server)

docs/src/languages/toml.md

@@ -0,0 +1,5 @@
+# TOML
+
+
+- Tree Sitter: [tree-sitter-toml](https://github.com/tree-sitter/tree-sitter-toml)
+- Language Server: N/A

docs/src/languages/tsx.md

@@ -0,0 +1,4 @@
+# TSX
+
+- Tree Sitter: [tree-sitter-typescript](https://github.com/tree-sitter/tree-sitter-typescript)
+- Language Server: [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)

docs/src/languages/typescript.md

@@ -0,0 +1,4 @@
+# TypeScript
+
+- Tree Sitter: [tree-sitter-typescript](https://github.com/tree-sitter/tree-sitter-typescript)
+- Language Server: [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server)

docs/src/languages/vue.md

@@ -0,0 +1,4 @@
+# Vue
+
+- Tree Sitter: [tree-sitter-vue](https://github.com/vuejs/language-tools/tree/master/packages/vue-language-server)
+- Language Server: [vue](https://github.com/vuejs/language-tools)

docs/src/languages/yaml.md

@@ -0,0 +1,4 @@
+# YAML
+
+- Tree Sitter: [tree-sitter-yaml](https://github.com/zed-industries/tree-sitter-yaml)
+- Language Server: [yaml-language-server](https://github.com/redhat-developer/yaml-language-server)

docs/src/languages/zig.md

@@ -0,0 +1,4 @@
+# Zig
+
+- Tree Sitter: [tree-sitter-zig](https://github.com/maxxnino/tree-sitter-zig)
+- Language Server: [zls](https://github.com/zigtools/zls)