feat!: deprecate the nvim-cmp, coq_nvim, and null-ls sources

The in-process language server can be used instead.

Author: saecki

doc/crates.txt

@@ -734,9 +734,6 @@ text.error                                          *crates-config-text-error*
     Format string used when there was an error loading crate information.
 
 
-open_programs                                    *crates-config-open_programs*
-    DEPRECATED: `vim.ui.open()` is used instead
-
 highlight                                            *crates-config-highlight*
     Section type: `HighlightConfig`
 
@@ -1414,6 +1411,7 @@ completion.cmp                                  *crates-config-completion-cmp*
 
 
 completion.cmp.enabled                  *crates-config-completion-cmp-enabled*
+    DEPRECATED: The nvim-cmp source will be removed soon. Use the in-process language server instead.
     Type: `boolean`, Default: `false`
 
     Whether to load and register the |nvim-cmp| source.
@@ -1478,6 +1476,7 @@ completion.coq                                  *crates-config-completion-coq*
 
 
 completion.coq.enabled                  *crates-config-completion-coq-enabled*
+    DEPRECATED: The coq_nvim source will be removed soon. Use the in-process language server instead.
     Type: `boolean`, Default: `false`
 
     Whether to load and register the |coq_nvim| source.
@@ -1590,21 +1589,24 @@ completion.crates.max_results    *crates-config-completion-crates-max_results*
 
 
 src                                                        *crates-config-src*
-    DEPRECATED: please use |crates-config-completion| instead.
-
+    DEPRECATED: This will be ignored.
+    Please use |crates-config-completion| instead.
 null_ls                                                *crates-config-null_ls*
+    DEPRECATED: The null-ls source will be removed soon. Use the in-process language server instead.
     Section type: `NullLsConfig`
 
     Configuration options for null-ls.nvim actions.
 
 
 null_ls.enabled                                *crates-config-null_ls-enabled*
+    DEPRECATED: The null-ls source will be removed soon. Use the in-process language server instead.
     Type: `boolean`, Default: `false`
 
     Whether to register the |null-ls.nvim| source.
 
 
 null_ls.name                                      *crates-config-null_ls-name*
+    DEPRECATED: The null-ls source will be removed soon. Use the in-process language server instead.
     Type: `string`, Default: `"crates.nvim"`
 
     The |null-ls.nvim| name.
@@ -1651,6 +1653,8 @@ lsp.on_attach                                    *crates-config-lsp-on_attach*
 
     Callback to run when the in-process language server attaches to a buffer.
 
+    NOTE: Alternatively you can also use the `LspAttach` autocmd.
+
     NOTE: Ignored if |crates-config-autoload| is disabled.
 
 

docgen/gen_doc.lua

@@ -284,7 +284,8 @@ end
 ---@param lines string[]
 ---@param path string[]
 ---@param schema SchemaElement[]
-local function gen_vimdoc_config(lines, path, schema)
+---@param parent_deprecated Deprecated?
+local function gen_vimdoc_config(lines, path, schema, parent_deprecated)
     for _, s in ipairs(schema) do
         if s.hidden then
             goto continue
@@ -302,34 +303,43 @@ local function gen_vimdoc_config(lines, path, schema)
             table.insert(lines, key)
         end
 
-        if s.deprecated then
-            if s.deprecated.new_field then
-                local nf = "crates-config-" .. table.concat(s.deprecated.new_field, "-")
-                table.insert(lines, string.format("    DEPRECATED: please use |%s| instead.", nf))
-            elseif s.deprecated.msg then
-                table.insert(lines, "    DEPRECATED: " .. s.deprecated.msg)
-            elseif s.deprecated.hard then
-                table.insert(lines, "    DEPRECATED: ignored")
-            end
-            table.insert(lines, "")
-        else
-            if s.type.config_type == "section" then
-                table.insert(lines, string.format("    Section type: `%s`", s.type.emmylua_annotation))
-                table.insert(lines, "")
+        local deprecated = s.deprecated or parent_deprecated
+        if deprecated then
+            if deprecated.msg then
+                local msg = string.sub(deprecated.msg, 1, 1):upper() .. string.sub(deprecated.msg, 2)
+                table.insert(lines, "    DEPRECATED: " .. msg)
+            elseif not deprecated.hard then
+                table.insert(lines, "    DEPRECATED: This will stop working soon.")
             else
-                local t = s.type.emmylua_annotation
-                local d = s.default_text or vim.inspect(s.default)
-                table.insert(lines, string.format("    Type: `%s`, Default: `%s`", t, d))
-                table.insert(lines, "")
+                table.insert(lines, "    DEPRECATED: This will be ignored.")
+            end
+            if deprecated.new_field then
+                local nf = "crates-config-" .. table.concat(deprecated.new_field, "-")
+                table.insert(lines, string.format("    Please use |%s| instead.", nf))
             end
+        end
+
+        if deprecated and deprecated.hard then
+            goto continue
+        end
+
+        if s.type.config_type == "section" then
+            table.insert(lines, string.format("    Section type: `%s`", s.type.emmylua_annotation))
+        else
+            local t = s.type.emmylua_annotation
+            local d = s.default_text or vim.inspect(s.default)
+            table.insert(lines, string.format("    Type: `%s`, Default: `%s`", t, d))
+        end
+        table.insert(lines, "")
 
+        if s.description then
             local description = s.description:gsub("^    ", ""):gsub("\n    ", "\n")
             table.insert(lines, description)
             table.insert(lines, "")
         end
 
         if s.type.config_type == "section" then
-            gen_vimdoc_config(lines, p, s.fields)
+            gen_vimdoc_config(lines, p, s.fields, deprecated)
         end
 
         ::continue::
@@ -348,7 +358,7 @@ local function gen_def_config(lines, indent, path, schema)
     end
 
     for _, s in ipairs(schema) do
-        if not s.hidden and not s.deprecated then
+        if not s.hidden and not (s.deprecated and (s.deprecated.hard or s.deprecated.new_field)) then
             local name = s.name
 
             if s.type.config_type == "section" then
@@ -396,7 +406,7 @@ local function gen_vim_doc()
             elseif ph == "SUBCOMMANDS" then
                 gen_vimdoc_subcommands(lines)
             elseif ph == "CONFIGURATION" then
-                gen_vimdoc_config(lines, {}, config.schema)
+                gen_vimdoc_config(lines, {}, config.schema, nil)
             elseif ph == "HIGHLIGHTS" then
                 gen_vimdoc_highlights(lines)
             else

docgen/templates/documentation.md.in

@@ -1,13 +1,10 @@
 Documentation for `crates.nvim` `<VERSION>`
 
 # Features
-- Complete crate names, versions and features using one of:
-    - In-process language server (`lsp`)
-    - [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) source (`completion.cmp`)
-    - [coq.nvim](https://github.com/ms-jpq/coq_nvim) source (`completion.coq`)
-- Code actions using one of:
-    - In-process language server (`lsp`)
-    - [null-ls.nvim](https://github.com/jose-elias-alvarez/null-ls.nvim)/[none-ls.nvim](https://github.com/nvimtools/none-ls.nvim)
+- In-process language server (`lsp`)
+    - Complete crate names, versions and features
+    - Code actions
+    - Hover
 - Update crates to newest compatible version
 - Upgrade crates to newest version
 - Respect existing version requirements and update them in an elegant way (`smart_insert`)
@@ -31,15 +28,19 @@ Documentation for `crates.nvim` `<VERSION>`
 # Setup
 
 ## In-process language server
-This is the recommended way to enable completion and code actions.
+The in-process langauge server is enabled by default. It provides support
+for completions, code actions, and hover through an lsp interface.
+
+The `on_attach` function, or the `LspAttach` autocmd can be used to setup
+key mappings, just like for other language servers. This is the default lsp
+configuration:
 
-Enable the in-process language server in the setup and select whether to enable
-code actions, auto completion and hover.
 ```lua
 require("crates").setup {
     ...
     lsp = {
         enabled = true,
+        name = "crates.nvim",
         on_attach = function(client, bufnr)
             -- the same on_attach function as for your other language servers
             -- can be ommited if you're using the `LspAttach` autocmd
@@ -52,56 +53,30 @@ require("crates").setup {
 ```
 
 ## Auto completion
-Completion is supported in a few different ways, either by the [in-process language server](#in-process-language-server),
-which also supports code actions, or by one of the following sources.
+Auto completion works through the [in-process language server](#in-process-language-server).
 
-### [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) source
+### Crate name completion
+
+Crate names of dependencies can be completed from searches on `crates.io`.
+This has to be enabled seperately:
 
-Enable it in the setup.
 ```lua
 require("crates").setup {
     ...
     completion = {
-        ...
-        cmp = {
-            enabled = true,
-        },
-    },
-}
-```
-
-And add it to your list of sources.
-```lua
-require("cmp").setup {
-    ...
-    sources = {
-        { name = "path" },
-        { name = "buffer" },
-        { name = "nvim_lsp" },
-        ...
-        { name = "crates" },
-    },
+        crates = {
+            enabled = true -- Disabled by default
+            max_results = 8 -- The maximum number of search results to display
+            min_chars = 3 -- The minimum number of charaters to type before completions begin appearing
+        }
+    }
 }
 ```
 
-<details>
-<summary>Or add it lazily.</summary>
-
-```lua
-vim.api.nvim_create_autocmd("BufRead", {
-    group = vim.api.nvim_create_augroup("CmpSourceCargo", { clear = true }),
-    pattern = "Cargo.toml",
-    callback = function()
-        cmp.setup.buffer({ sources = { { name = "crates" } } })
-    end,
-})
-```
-</details>
-
-<details>
-<summary>Custom nvim-cmp completion kinds</summary>
+### [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) source
 
-Enable custom completion kind in the config.
+Custom completion kinds are enabled by default, but icons need to be specified
+manually. The default kind names and highlight groups are as follows:
 ```lua
 require("crates").setup {
     ...
@@ -125,11 +100,12 @@ require("crates").setup {
 This will set a custom completion `cmp.kind_text` and `cmp.kind_hl_group` attributes
 to completion items for `nvim-cmp`.
 
-Depending on how you've set up [the nvim-cmp menu](https://github.com/hrsh7th/nvim-cmp/wiki/Menu-Appearance#basic-customisations)
-you'll have to handle these explicitly.
-If you haven't changed `nvim-cmp`s `formatting` configuration everything should work out of the box.
+<details>
+<summary>Custom nvim-cmp kind icons</summary>
+
+How custom icons can be added depends on how you've set up [the nvim-cmp menu](https://github.com/hrsh7th/nvim-cmp/wiki/Menu-Appearance#basic-customisations).
 
-Here's an example of how add custom icons.
+Here's an example of how add custom icons, you might need to adapt some things.
 ```lua
 local kind_icons = {
     ["Class"] = "🅒 ",
@@ -175,57 +151,15 @@ require("cmp").setup({
 ```
 </details>
 
-### [coq.nvim](https://github.com/ms-jpq/coq_nvim) source
-Enable it in the setup, and optionally change the display name.
-```lua
-require("crates").setup {
-    ...
-    completion = {
-        ...
-        coq = {
-            enabled = true,
-            name = "crates.nvim",
-        },
-    },
-}
-```
-
-### Crate name completion
-
-Crate names in dependencies can be completed from searches on `crates.io`. This has to be
-enabled seperately:
-
-```lua
-require("crates").setup {
-    ...
-    completion = {
-        crates = {
-            enabled = true -- disabled by default
-            max_results = 8 -- The maximum number of search results to display
-            min_chars = 3 -- The minimum number of charaters to type before completions begin appearing
-        }
-    }
-}
-```
-
 ## Code actions
-Code actions are supported in a few different ways, either by the [in-process language server](#in-process-language-server),
-which also supports completion, or by the null-ls/none-ls source.
+Code actions work through the [in-process language server](#in-process-language-server).
+But you can also set up key mappings for specific actions. See [key mappings](#key-mappings).
 
-### [null-ls.nvim](https://github.com/jose-elias-alvarez/null-ls.nvim)/[none-ls.nvim](https://github.com/nvimtools/none-ls.nvim) source
-Enable it in the setup, and optionally change the display name.
-```lua
-require("crates").setup {
-    ...
-    null_ls = {
-        enabled = true,
-        name = "crates.nvim",
-    },
-}
-```
+## Hover
+Hover is supported through the [in-process language server](#in-process-language-server).
+But you can also set up key mappings for specific menus. See [key mappings](#key-mappings).
 
 # Config
-
 For more information about the config types have a look at the vimdoc or [`lua/crates/config/types.lua`](https://github.com/Saecki/crates.nvim/blob/main/lua/crates/config/types.lua).
 
 ## Default