docs: migrate docs to vim.lsp.config #3709

2 files changed, 79 insertions, 179 deletions

diff --git a/README.md b/README.md
index d2246f88..a5b50c49 100644
--- a/README.md
+++ b/README.md
@@ -3,17 +3,15 @@
 nvim-lspconfig is a "data only" repo, providing basic, default [Nvim LSP client](https://neovim.io/doc/user/lsp.html)
 configurations for various LSP servers.
 
-View the [documentation for all configs](doc/configs.md) or `:help lspconfig-all` from Nvim.
+View [all configs](doc/configs.md) or `:help lspconfig-all` from Nvim.
 
 ## Important ⚠️
 
-* If you found a bug in the Nvim LSP functionality (`:help lsp`), [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
+* These configs are **best-effort and supported by the community (you).** See [contributions](#contributions).
+* If you found a bug in Nvim LSP (`:help lsp`), [report it to Neovim core](https://github.com/neovim/neovim/issues/new?assignees=&labels=bug%2Clsp&template=lsp_bug_report.yml).
     * **Do not** report it here. Only configuration data lives here.
-* These configs are **best-effort and supported by the community.** See [contributions](#contributions).
-* **Note:** This repo only provides *configurations*. Its programmatic API is deprecated and should not be used externally.
-    * [Work is planned](https://github.com/neovim/neovim/issues/28479) to selectively upstream the
-      "framework" parts (*not* the configs) of nvim-lspconfig, to Nvim core, and deprecate them in
-      nvim-lspconfig.
+* This repo only provides *configurations*. Its programmatic API is deprecated and must not be used externally.
+    * The "framework" parts (*not* the configs) of nvim-lspconfig [will be upstreamed to Nvim core](https://github.com/neovim/neovim/issues/28479).
 
 ## Install
 
@@ -33,17 +31,15 @@ View the [documentation for all configs](doc/configs.md) or `:help lspconfig-all
    npm i -g pyright
    ```
 2. Add the language server setup to your init.lua.
-   ```lua
-   -- neovim < 0.11
-   require'lspconfig'.pyright.setup{}
-   -- neovim >= 0.11
-   vim.lsp.enable('pyright')
-   ```
-
-    > For more information see [`vim.lsp` support](#vim.lsp-support).
-
-3. Ensure your project/workspace contains a root marker which matches the server requirements
-   specified in `:help lspconfig-all`.
+    - Nvim 0.11+ (see [vim.lsp.config](#vim.lsp.config))
+      ```lua
+      vim.lsp.enable('pyright')
+      ```
+    - Nvim 0.10 (legacy, **not supported**)
+      ```lua
+      require'lspconfig'.pyright.setup{}
+      ```
+3. Ensure your project/workspace contains a root marker as specified in `:help lspconfig-all`.
 4. Open a code file in Nvim. LSP will attach and provide diagnostics.
    ```
    nvim main.py
@@ -51,7 +47,7 @@ View the [documentation for all configs](doc/configs.md) or `:help lspconfig-all
 5. Run `:checkhealth lsp` to see the status or to troubleshoot.
 
 Read `:help lspconfig` for details. Read `:help lspconfig-all` for the full list of server-specific details.
-For servers not on your `$PATH` (e.g., `jdtls`, `elixirls`), you must manually set the `cmd` parameter, see [configuration](#Configuration).
+For servers not on your `$PATH` (e.g., `jdtls`, `elixirls`), you must manually set the `cmd` parameter, see [vim.lsp.config](#vim.lsp.config).
 
 ## Configuration
 
@@ -85,35 +81,31 @@ See [`:h lsp-buf`][lsp-buf] for details on other LSP functions.
 [LspDetach]: https://neovim.io/doc/user/lsp.html#LspDetach
 [lsp-buf]: https://neovim.io/doc/user/lsp.html#lsp-buf
 
-Additional configuration options can be provided for each LSP server:
-
-- `neovim < 0.11`
+Extra settings can be specified for each LSP server:
 
-    ```lua
-    local lspconfig = require('lspconfig')
-    lspconfig.rust_analyzer.setup {
-      -- Server-specific settings. See `:help lspconfig-setup`
-      settings = {
-        ['rust-analyzer'] = {},
-      },
-    }
-    ```
-
-- `neovim >= 0.11`
-
-    ```lua
-    vim.lsp.config('rust_analyzer', {
-      -- Server-specific settings. See `:help lspconfig-setup`
-      settings = {
-        ['rust-analyzer'] = {},
-      },
-    })
-    ```
-    > For more information see [`vim.lsp` support](#vim.lsp-support).
+- Nvim 0.11+ (see [vim.lsp.config](#vim.lsp.config))
+  ```lua
+  vim.lsp.config('rust_analyzer', {
+    -- Server-specific settings. See `:help lsp-quickstart`
+    settings = {
+      ['rust-analyzer'] = {},
+    },
+  })
+  ```
+- Nvim 0.10 (legacy, **not supported**)
+  ```lua
+  local lspconfig = require('lspconfig')
+  lspconfig.rust_analyzer.setup {
+    -- Server-specific settings. See `:help lspconfig-setup`
+    settings = {
+      ['rust-analyzer'] = {},
+    },
+  }
+  ```
 
-## `vim.lsp` support
+## vim.lsp.config
 
-`nvim-lspconfig` includes configurations compatible with `vim.lsp` under [`lsp/`](./lsp/), so servers can be enabled with:
+`nvim-lspconfig` includes configurations compatible with `vim.lsp` under [`lsp/`](./lsp/), so servers can be enabled (auto-activated when a filetype is opened) with:
 
 ```lua
 vim.lsp.enable('pyright')
@@ -122,13 +114,15 @@ vim.lsp.enable('pyright')
 and configured with:
 
 ```lua
-vim.lsp.config('pyright', {})
+vim.lsp.config('pyright', {
+  cmd = { … },
+})
 ```
 
 which extends the configuration under [`lsp/`](./lsp/). For further information see [`:help lsp-config`][lsp-config].
 
 > [!WARNING]  
-> Some servers are currently NOT supported and should be configured the old way, see `:help lspconfig-setup`
+> Some servers are [currently missing](https://github.com/neovim/nvim-lspconfig/issues/3705).
 
 ## Troubleshooting
 
@@ -178,7 +172,7 @@ a new configuration for it helps others, especially if the server requires speci
       [texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/texlab.lua).
 3. Ask questions on [GitHub Discussions](https://github.com/neovim/neovim/discussions) or in the [Neovim Matrix room](https://app.element.io/#/room/#neovim:matrix.org).
 
-### Release process
+## Release process
 
 To publish a release:
 
diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt
index afe9e5bd..c382d952 100644
--- a/doc/lspconfig.txt
+++ b/doc/lspconfig.txt
@@ -20,88 +20,50 @@ QUICKSTART                                                *lspconfig-quickstart*
 1. Install a language server, e.g. pyright. >bash
    npm i -g pyright
 2. Add the language server setup to your init.lua. >lua
-   require'lspconfig'.pyright.setup{}
-3. Ensure your project/workspace contains a root marker which matches the
-   server requirements specified in |lspconfig-all|.
+   vim.lsp.enable('pyright')
+3. Ensure your workspace contains a root marker as specified in
+   |lspconfig-all|.
 4. Open a code file in Nvim. LSP will attach and provide diagnostics. >bash
    nvim main.py
-5. Run `:checkhealth lsp` to see the status or to troubleshoot.
+5. Run `:checkhealth vim.lsp` to see the status or troubleshoot.
+
+See also |lsp-quickstart|.
 
 ==============================================================================
 USAGE                                                        *lspconfig-usage*
 
-`lspconfig` consists of a collection of language server configurations. Each
-configuration exposes a `setup{}` metamethod which makes it easy to directly
-use the default configuration or selectively override the defaults. `setup{}`
-is the primary interface by which users interact with `lspconfig`.
+nvim-lspconfig is of a collection of language server configurations. Each
+configuration provides defaults for |vim.lsp.config()| which you can use as-is
+(by calling `vim.lsp.enable(…)`) or override (by calling |vim.lsp.config()|
+before enable()).
 
-To activate a config, call its `setup{}` function. Each config name listed in
-|lspconfig-all| is available as `config.<name>`. For example to activate the
-"clangd" config: >lua
+To activate a config, call |vim.lsp.enable()|. Each config in |lspconfig-all|
+is available as `vim.lsp.config('<name>')` and `vim.lsp.enable('<name>')`. For
+example to activate the "clangd" config: >lua
 
-    require'lspconfig'.clangd.setup{}
+    -- Optionally override parts of the default config...
+    vim.lsp.config('clangd', {
+      …
+    })
+    -- Enable filetype-based activation of the config.
+    vim.lsp.enable('clangd')
 <
-                                                        *lspconfig-config_def*
-You can use the `config_def` field to get the static config definition without
-activating it: >lua
+                                                          *lspconfig-resolved*
+You can call the "index" form of vim.lsp.config to get the resolved config
+without activating it: >lua
 
-    local config = require'lspconfig'.clangd.config_def
+    vim.print(vim.lsp.config['clangd'])
 <
-                                                             *lspconfig-setup*
-`setup{}` wraps |vim.lsp.start()|, and takes a superset of its parameters,
-adding the following keys:
-
-- {filetypes} (`list[string] | nil`) Set of filetypes for which to attempt to
-  resolve {root_dir}. May be empty, or server may specify a default value.
-
-- {autostart} (`bool`) (default: true) Controls if the `FileType` autocommand
-  that launches a language server is created. If `false`, allows for deferring
-  language servers until manually launched with `:LspStart`.
-
-- {single_file_support} (`bool`) (default: nil) Determines if a server is
-  started without a matching root directory. See |lspconfig-single-file-support|.
-
-- {silent} (`bool`) (default: false) Whether to suppress error reporting if the
-  LSP server fails to start.
-
-- {on_new_config} (`function(new_config, new_root_dir)`) Function executed
-  after a root directory is detected. This is used to modify the server
-  configuration (including `cmd` itself). Most commonly, this is used to
-  inject additional arguments into `cmd`.
-
-  If overriding `on_new_config`, ensure that you read the `on_new_config`
-  defined in the source file of the default configuration in `lspconfig`. The
-  original `on_new_config` snippet for a given server should likely be
-  included in your new override. Some configurations use `on_new_config` to
-  dynamically set or modify `cmd`.
-
-Note: all fields passed to `setup{}` override the respective field in the
-default configuration. There is no composition.
-
-All |vim.lsp.start()| `config` fields (described in |vim.lsp.ClientConfig|)
-can be overridden via the `setup{}` call. The most common overrides are:
+                                                 *lspconfig-vs-vim.lsp.config*
+Note the these current differences/limitations of |vim.lsp.config()| compared
+to the legacy nvim-lspconfig interface:
 
-- {settings} Table is sent after initialization via
-  a `workspace/didChangeConfiguration` notification from the Nvim client to
-  the language server. These settings allow a user to change optional runtime
-  settings of the language server.
+- `single_file_support` is assumed by default. Can be disabled by specifying
+  `workspace_required=false` (see |vim.lsp.ClientConfig|).
 
-  Example: set the following settings found in the pyright documentation:
-
-  `pyright.disableLanguageServices`: `boolean`
-  `pyright.disableOrganizeImports`: `boolean`
-
-  Nested keys need to be translated into a nested table and passed to
-  the settings field in `setup{}` as follows: >lua
-  require('lspconfig').pyright.setup{
-    settings = {
-      pyright = {
-          disableLanguageServices = true,
-          disableOrganizeImports  = true,
-        }
-    }
-  }
-<
+- `on_new_config` is currently missing, see https://github.com/neovim/neovim/issues/32287
+  Function executed after a root directory is detected. Used to modify the
+  server configuration (including `cmd` itself).
 
 ==============================================================================
 COMMANDS                                                    *lspconfig-commands*
@@ -130,8 +92,8 @@ SERVER CONFIGS                                        *lspconfig-configurations*
 
 See |lspconfig-all| for the list of provided LSP configurations.
 
-For servers that don't have a config, define one via `vim.lsp.config()`
-(requires Nvim 0.11 or later), see |lsp-config|.
+If a server is missing, you can define one easily via |vim.lsp.config()|
+(requires Nvim 0.11+), see |lsp-config|.
 
 ==============================================================================
 COMPLETION SUPPORT                                        *lspconfig-completion*
@@ -141,51 +103,13 @@ See |lsp-completion|.
 ==============================================================================
 ADDING NEW SERVERS                                    *lspconfig-new*
 
-See |lsp-config| (requires Nvim 0.11 or later).
-
-==============================================================================
-ROOT DETECTION                                        *lspconfig-root-detection*
-
-A project's `root_dir` is used by `lspconfig` to determine whether `lspconfig`
-should start a new server, or attach a previous one, to the current file.
-
-Nvim provides |vim.fs.root()| to make it easy to find a "root marker" file.
-
-==============================================================================
-ADVANCED ROOT DIRECTORY DETECTION                      *lspconfig-root-advanced*
-The `root_dir` field of |vim.lsp.Config| (Nvim 0.11 or later) may be
-a function.
-
-==============================================================================
-SINGLE FILE SUPPORT                              *lspconfig-single-file-support*
-
-Language servers require each project to have a `root` in order to provide
-features that require cross-file indexing. 
-
-Some servers support not passing a root directory as a proxy for single file
-mode under which cross-file features may be degraded.
-
-`lspconfig` offers limited support for an implicit single-file mode by:
-
-- first trying to resolve the root directory pattern
-- then, if `single_file_support` is enabled for a given language server
-  configuration, starting the server without sending `rootDirectory` or
-  `workspaceFolders` during initialization.
-- attaching subsequent files in the parent directory to the same server
-  instance, depending on filetype.
-- also supports unnamed buffer if filetype matches the server filetype
-  settings.
-
-Cross-file features (navigation, hover) may or may not work depending on the
-language server. For a full feature-set, consider moving your files to a
-directory with a project structure `lspconfig` can infer.
-
-Note that in the event that the LSP specification is extended to support a
-standard for single-file mode, lspconfig will adopt that standard.
+See ../CONTRIBUTING.md or |lsp-config| (requires Nvim 0.11+).
 
 ==============================================================================
 DEBUGGING AND TROUBLESHOOTING                              *lspconfig-debugging*
 
+See |lsp-log| to enable verbose logs.
+
 While using language servers should be easy, debugging issues can be
 challenging. First, it is important to identify the source of the issue, which
 is typically (in rough order):
@@ -225,7 +149,7 @@ For debugging nvim-lspconfig issues, the most common hurdles users face are:
     Vim/Nvim because they have not yet been added to the filetype detection
     system. Ensure `:set ft?` shows the filetype and not an empty value.
   - Not triggering root detection. nvim-lspconfig is built around the concept
-    of projects. See |lspconfig-root-detection|.
+    of projects.
   - Not triggering root detection. Some language servers will only start
     if it is opened in a directory, or child directory, containing a file
     which signals the *root* of the project. Most of the time, this is
@@ -238,23 +162,5 @@ For debugging nvim-lspconfig issues, the most common hurdles users face are:
 |:LspInfo| provides an overview which can be useful for debugging.
 
 ==============================================================================
-LOGGING                                                      *lspconfig-logging*
-
-When debugging language servers, it is helpful to enable additional logging in
-the built-in client, specifically considering the RPC logs. Example: >lua
-
-  vim.lsp.set_log_level 'trace'
-  require('vim.lsp.log').set_format_func(vim.inspect)
-<
-Attempt to run the language server, and open the log with:
-
->vim
-    :LspLog
-<
-Note that `ERROR` messages containing `stderr` only indicate that the log was
-sent to `stderr`. Many servers counter-intuitively send harmless messages
-via stderr.
-
-==============================================================================
 
 vim:tw=78:ts=8:ft=help:norl: