docs: improve docs on new LSP API

docs/manual/configuring/languages/lsp.md

@@ -1,23 +1,41 @@
-# LSP Custom Packages/Command {#sec-languages-custom-lsp-packages}
+# Configuring supported LSP servers {#sec-languages-configuraing-lsp-servers}
 
 One of the strengths of **nvf** is convenient aliases to quickly configure LSP
 servers through the Nix module system. By default the LSP packages for relevant
 language modules will be pulled into the closure. If this is not desirable, you
-may provide **a custom LSP package** (e.g., a Bash script that calls a command)
-or **a list of strings** to be interpreted as the command to launch the language
-server. By using a list of strings, you can use this to skip automatic
-installation of a language server, and instead use the one found in your `$PATH`
-during runtime, for example:
+may modify [](#opt-vim.lsp.servers._name_.cmd) (see example below).
+
+Any other forms of configuration can be done via [](#opt-vim.lsp.servers), which
+is a wrapper for the Neovim Lua API available as`vim.lsp.config()`. Getting
+familiar with `:help vim.lsp.config()` may help you better understand how to
+configure LSPs.
 
 ```nix
-vim.languages.java = {
-  lsp = {
+{
+  vim.languages.python = {
     enable = true;
+    lsp = {
+      enable = true;
+      # You can now enable multiple LSPs per language
+      servers = ["basedpyright"];
+    };
+  };
+
+  # vim.lsp.servers is a wrapper for the lua API vim.lsp.config
+  # (see :help vim.lsp.config)
+  vim.lsp.servers = {
+    basedpyright = {
+      # `vim.languages.<lang>.lsp.package` is now removed, you have to
+      # modify the cmd field, and remember to copy over the arguments!
+      cmd = [(getExe pkgs.myCustomPackage) "--stdio"];
 
-    # This expects 'jdt-language-server' to be in your PATH or in
-    # 'vim.extraPackages.' There are no additional checks performed to see
-    # if the command provided is valid.
-    package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
+      # server specific settings, see documentation of the respective language
+      # servers
+      settings = {
+        basedpyright.analysis.logLevel = "Error";
+        python.pythonPath = getExe pkgs.myPython3;
+      };
+    };
   };
 }
 ```

docs/release-notes/rl-0.8.md

@@ -28,6 +28,62 @@
   align with the "hunks" themed mapping and avoid conflict with the new [neogit]
   group.
 
+- Language modules are reworked to allow more flexible and close-to-neovim-API
+  configs. LSP configuration options are removed from `vim.languages` and should
+  be done via `vim.lsp.servers`.
+
+## Language module LSP rework
+
+In nvf v0.8, language modules are overhauled, with a few goals in mind:
+
+1. Get rid of our rigid "hard-coded" Lua scripts in favor of the more flexible
+   `setupOpts` styled options
+2. Have our new API stick closer to Lua APIs, in this case `vim.lsp.config`
+3. Allow enabling multiple LSPs per-language
+
+This is, however, a big change, so breaking changes are inevitable. The most
+important change is the removal of `vim.languages.<lang>.lsp.package` - you now
+need to modify `vim.lsp.servers.<server>.cmd`, copying over any additional
+arguments - these can be found in the source code files of the respective
+language.
+
+<!-- TODO: add [!NOTE] admonitions when available-->
+
+The `<server>` mentioned here is the name of the language server, as shown in
+`vim.languages.<lang>.lsp.servers`. This is NOT the name of the language.
+
+Here's a quick overview at what the new language module, looks like:
+
+```nix
+{
+  vim.languages.python = {
+    enable = true;
+    lsp = {
+      enable = true;
+      # You can now enable multiple LSPs per language
+      servers = ["pyright" "python-lsp-server"];
+    };
+  };
+
+  # vim.lsp.servers is a wrapper for the lua API vim.lsp.config
+  # (see :help vim.lsp.config)
+  vim.lsp.servers = {
+    pyright = {
+      # `vim.languages.<lang>.lsp.package` is now removed, you have to
+      # modify the cmd field, and remember to copy over the arguments!
+      cmd = [(getExe pkgs.myCustomPyright) "--stdio"];
+    };
+
+    python-lsp-server = {
+      # server specific settings
+      settings = {
+        pylsp.signature.line_length = 100;
+      };
+    };
+  };
+}
+```
+
 [NotAShelf](https://github.com/notashelf):
 
 [typst-preview.nvim]: https://github.com/chomosuke/typst-preview.nvim

modules/neovim/init/lsp.nix

@@ -41,24 +41,22 @@ in {
       servers = mkOption {
         type = attrsOf lspOptions;
         default = {};
-        example = ''
-          {
-            "*" = {
-              root_markers = [".git"];
-              capabilities = {
-                textDocument = {
-                  semanticTokens = {
-                    multilineTokenSupport = true;
-                  };
+        example = {
+          "*" = {
+            root_markers = [".git"];
+            capabilities = {
+              textDocument = {
+                semanticTokens = {
+                  multilineTokenSupport = true;
                 };
               };
             };
+          };
 
-            "clangd" = {
-              filetypes = ["c"];
-            };
-          }
-        '';
+          "clangd" = {
+            filetypes = ["c"];
+          };
+        };
         description = ''
           LSP configurations that will be managed using `vim.lsp.config()` and related
           utilities added in Neovim 0.11. LSPs defined here will be added to the

modules/plugins/languages/asm.nix

@@ -36,7 +36,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Assembly LSP server to use";
+        description = ''
+          Assembly LSP server to use. Customization of the servers can be done
+          via [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/astro.nix

@@ -91,7 +91,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Astro LSP server to use";
+        description = ''
+          Astro LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/bash.nix

@@ -57,7 +57,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Bash LSP server to use";
+        description = ''
+          Bash LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/clang.nix

@@ -197,7 +197,10 @@ in {
       enable = mkEnableOption "clang LSP support" // {default = config.vim.lsp.enable;};
 
       servers = mkOption {
-        description = "The clang LSP server to use";
+        description = ''
+          The clang LSP server to use. Customization of the servers can be done
+          via [](#opt-vim.lsp.servers).
+        '';
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
       };

modules/plugins/languages/clojure.nix

@@ -37,7 +37,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Clojure LSP server to use";
+        description = ''
+          Clojure LSP server to use. Customization of the servers can be done
+          via [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/csharp.nix

@@ -185,7 +185,10 @@ in {
       lsp = {
         enable = mkEnableOption "C# LSP support" // {default = config.vim.lsp.enable;};
         servers = mkOption {
-          description = "C# LSP server to use";
+          description = ''
+            C# LSP server to use. Customization of the servers can be done via
+            [](#opt-vim.lsp.servers).
+          '';
           type = singleOrListOf (enum (attrNames servers));
           default = defaultServers;
         };

modules/plugins/languages/css.nix

@@ -76,7 +76,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServer;
-        description = "CSS LSP server to use";
+        description = ''
+          CSS LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/dart.nix

@@ -54,7 +54,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Dart LSP server to use";
+        description = ''
+          Dart LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/elixir.nix

@@ -65,7 +65,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Elixir LSP server to use";
+        description = ''
+          Elixir LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/fsharp.nix

@@ -74,7 +74,10 @@ in {
         servers = mkOption {
           type = singleOrListOf (enum (attrNames servers));
           default = defaultServer;
-          description = "F# LSP server to use";
+          description = ''
+            F# LSP server to use. Customization of the servers can be done via
+            [](#opt-vim.lsp.servers).
+          '';
         };
       };
       format = {

modules/plugins/languages/gleam.nix

@@ -37,7 +37,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Gleam LSP server to use";
+        description = ''
+          Gleam LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/go.nix

@@ -97,7 +97,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Go LSP server to use";
+        description = ''
+          Go LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/haskell.nix

@@ -78,7 +78,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Haskell LSP server to use";
+        description = ''
+          Haskell LSP server to use. Customization of the servers can be done
+          via [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/hcl.nix

@@ -44,7 +44,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "HCL LSP server to use";
+        description = ''
+          HCL LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/helm.nix

@@ -53,7 +53,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Helm LSP server to use";
+        description = ''
+          Helm LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/html.nix

@@ -60,7 +60,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "HTML LSP server to use";
+        description = ''
+          HTML LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/java.nix

@@ -74,7 +74,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Java LSP server to use";
+        description = ''
+          Java LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/json.nix

@@ -51,7 +51,10 @@ in {
       servers = mkOption {
         type = singleOrListOf (enum (attrNames servers));
         default = defaultServers;
-        description = "JSON LSP server to use";
+        description = ''
+          JSON LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
 

modules/plugins/languages/just.nix

@@ -39,7 +39,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Just LSP server to use";
+        description = ''
+          Just LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };
   };

modules/plugins/languages/kotlin.nix

@@ -65,7 +65,10 @@ in {
       servers = mkOption {
         type = listOf (enum (attrNames servers));
         default = defaultServers;
-        description = "Kotlin LSP server to use";
+        description = ''
+          Kotlin LSP server to use. Customization of the servers can be done via
+          [](#opt-vim.lsp.servers).
+        '';
       };
     };