Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saecki merged 1 commit into from
Aug 2, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions doc/crates.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.


Expand Down
54 changes: 32 additions & 22 deletions docgen/gen_doc.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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::
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
132 changes: 32 additions & 100 deletions docgen/templates/documentation.md.in
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`)
Expand All @@ -31,10 +28,12 @@ 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 disabled by default. It can be enabled
to support completions, code actions, and hover.

Enable the in-process language server in the setup and select whether to enable
code actions, auto completion and hover.
code actions, auto completion and hover. The `on_attach` function, or the `LspAttach`
autocmd can be used to setup key mappings, just like for other language servers.
```lua
require("crates").setup {
...
Expand All @@ -52,56 +51,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 {
...
Expand All @@ -125,11 +98,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"] = "🅒 ",
Expand Down Expand Up @@ -175,57 +149,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
Expand Down
Loading