docs: update contributing.md to new style lsp config #3712

Problem:
Contributing guide describes old style of lsp configuration.

Solution:
Change to explain new style.

1 files changed, 33 insertions, 57 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e18932cb..734b32eb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,14 +25,10 @@ New configs must meet these criteria (to avoid spam/quasi-marketing/vanity proje
 This helps ensure that we only include actively maintained and widely used servers to provide a better experience for
 the community.
 
-To add a new language server, start with a minimal skeleton. See `:help lspconfig-new`.
+To add a new language server, start with a minimal skeleton. See `:help lspconfig-new` and other configurations in `lsp/`.
 
 When choosing a config name, convert dashes (`-`) to underscores (`_`). If the name of the server is a unique name (`pyright`, `clangd`) or a commonly used abbreviation (`zls`), prefer this as the server name. If the server instead follows the pattern x-language-server, prefer the convention `x_ls` (`jsonnet_ls`). 
 
-Populate the `config` table with `default_config` and `docs` tables. Avoid over-architected code. Put lists directly in
-the `default_config` don't add indirection by defining variables elsewhere in the module. The docs are auto-generated by
-reading your `config` source code, so the less indirection in your code, the more useful and obvious the docs will be.
-
 `default_config` should include:
 
 * `cmd`: a list which includes the executable name as the first entry, with arguments constituting subsequent list elements (`--stdio` is common).
@@ -40,65 +36,45 @@ reading your `config` source code, so the less indirection in your code, the mor
   cmd = { 'typescript-language-server', '--stdio' }
   ```
 * `filetypes`: list of filetypes that should activate this config.
-* `root_dir`: function which returns the root of the project, used to decide if lspconfig should launch a new language server, or attach a previously launched server when you open a new buffer matching the filetype of the server.
+* `root_markers`: a list of files that mark the root of the project.
     * See `:help lspconfig-new`.
     * See `vim.fs.root()`
-    * Do not use `vim.fn.cwd` or `vim.fs.dirname`.
-
-Additionally, these options are often useful:
-
-* `init_options`: table sent during initialization, corresponding to `initializationOptions` sent in [initializeParams](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initializeParams) as part of the first request sent from client to server during startup.
-* `settings`: table sent during [`workspace/didChangeConfiguration`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#didChangeConfigurationParams) shortly after server initialization. This is an undocumented convention for most language servers. There is often some duplication with `initOptions`.
 
-An example for adding a new config is shown below:
+An example for adding a new config `lsp/pyright.lua` is shown below:
 
 ```lua
-local util = require 'lspconfig.util'
-
 local function organize_imports()
-  local params = {
-    command = 'pyright.organizeimports',
-    arguments = { vim.uri_from_bufnr(0) },
-  }
-  vim.lsp.buf.execute_command(params)
+  -- executes lsp command. See `lsp/pyright.lua` for the full example.
 end
 
+---@brief
+---
+-- https://github.com/microsoft/pyright
+--
+-- `pyright`, a static type checker and language server for python
 return {
-  default_config = {
-    cmd = { 'pyright-langserver', '--stdio' },
-    filetypes = { 'python' },
-    root_dir = util.root_pattern(
-      'pyproject.toml',
-      'setup.py',
-      'setup.cfg',
-      'requirements.txt',
-      'Pipfile',
-      'pyrightconfig.json',
-    ),
-    single_file_support = true,
-    settings = {
-      python = {
-        analysis = {
-          autoSearchPaths = true,
-          useLibraryCodeForTypes = true,
-          diagnosticMode = 'workspace',
-        },
-      },
-    },
+  cmd = { 'pyright-langserver', '--stdio' },
+  filetypes = { 'python' },
+  root_markers = {
+    'pyproject.toml',
+    'setup.py',
+    'setup.cfg',
+    'requirements.txt',
+    'Pipfile',
+    'pyrightconfig.json',
   },
-  commands = {
-    PyrightOrganizeImports = {
-      organize_imports,
-      description = 'Organize Imports',
+  settings = {
+    python = {
+      analysis = {
+        autoSearchPaths = true,
+        useLibraryCodeForTypes = true,
+        diagnosticMode = 'workspace',
+      },
     },
   },
-  docs = {
-    description = [[
-https://github.com/microsoft/pyright
-
-`pyright`, a static type checker and language server for python
-]],
-  },
+  on_attach = function()
+    vim.api.nvim_buf_create_user_command(0, 'PyrightOrganizeImports', organize_imports, {})
+  end,
 }
 ```
 
@@ -106,13 +82,13 @@ https://github.com/microsoft/pyright
 
 Follow the Neovim core [commit message guidelines](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#commit-messages). Examples:
 
-* Adding a new config for "lua-language-server":
+* Adding a new config for "lua_ls":
   ```
-  feat: lua-language-server
+  feat: lua_ls
   ```
-* Fixing a bug for "lua-language-server":
+* Fixing a bug for "lua_ls":
   ```
-  fix(lua-language-server): update root directory pattern
+  fix(lua_ls): update root directory pattern
 
   Problem:
   Root directory incorrectly prefers "foo".
@@ -137,7 +113,7 @@ If using nix, you can use `nix develop` to install these to a local nix shell.
 ## Generating docs
 
 GitHub Actions automatically generates `configs.md`. Only modify
-`scripts/docs_template.md` or the `docs` table in the config code.
+`scripts/docs_template.md` or the docstrings in the source of the config file.
 Do not modify `configs.md` directly.
 
 To preview the generated `configs.md` locally, run `scripts/docgen.lua` from