Problem:
gen_vimdoc.py / lua2dox.lua does not support @defgroup or \defgroup
except for "api-foo" modules.
Solution:
Modify `gen_vimdoc.py` to look for section names based on `helptag_fmt`.
TODO:
- Support @module ?
https://github.com/LuaLS/lua-language-server/wiki/Annotations#module
Problem:
Help tags like vim.treesitter.language.add() are confusing because
`vim.treesitter.language` is (thankfully) not a user-facing module.
Solution:
Ignore the "fstem" when generating "treesitter" tags.
https://github.com/neovim/neovim/pull/22398 broke the job because there
is no `build/bin/nvim`
This keeps the preference for `build/bin/nvim` but adds back `nvim` as
fallback if it doesn't exist.
Problem:
Nvim has Lua but the "nvim" CLI can't easily be used to execute Lua
scripts, especially scripts that take arguments or produce output.
Solution:
- support "nvim -l [args...]" for running scripts. closes#15749
- exit without +q
- remove lua2dox_filter
- remove Doxyfile. This wasn't used anyway, because the doxygen config
is inlined in gen_vimdoc.py (`Doxyfile` variable).
- use "nvim -l" in docs-gen CI job
Examples:
$ nvim -l scripts/lua2dox.lua --help
Lua2DoX (0.2 20130128)
...
$ echo "print(vim.inspect(_G.arg))" | nvim -l - --arg1 --arg2
$ echo 'print(vim.inspect(vim.api.nvim_buf_get_text(1,0,0,-1,-1,{})))' | nvim +"put ='text'" -l -
TODO?
-e executes Lua code
-l loads a module
-i enters REPL _after running the other arguments_.
* credit to @smolck and @theHamsta for their contributions in laying the
groundwork for this feature and for their work on some of the helper
utility functions and tests
This function accepts a path to a file and prompts the user if the file
is trusted. If the user confirms that the file is trusted, the contents
of the file are returned. The user's decision is stored in a trust
database at $XDG_STATE_HOME/nvim/trust. When this function is invoked
with a path that is already marked as trusted in the trust database, the
user is not prompted for a response.
Problem:
The {foo} parameters listed in `:help api` and similar generated docs,
are intended to be a "list" but they aren't prefixed with a list symbol.
This prevents parsers from understanding the list, which forces
generators like `gen_help_html.lua` to use hard-wrapped/preformatted
layout instead of a soft-wrapped "flow" layout.
Solution:
Modify gen_vimdoc.py to prefix {foo} parameters with a "•" symbol.
In case nvim A sends nvim_error_event to nvim B, it would
respond with another nvim_error_event due to unknown
request name. Fix this by adding dummy request handler for now.
When checking the version of the doxygen installed from conda the output
has the following format:
1.9.2 (ee54ebd4f0ad83d9c44f19a459146de64d0ffba2*)
This would cause an error in the "Missing API docs" CI job. This fix
will correctly parse the doxygen version for both stable releases
("1.9.2") as well as the version with the git commit hash attached.
There have been a few instances where developers got confused as to why
their generated documentation differs from the one generated by the CI.
More often than not, the reason is that their doxygen version is older
than 1.9.0, which is the current minimum version. Having a simple
version check will help save future developers avoid this problem.
Previously, `delete_lines_below` would raise `FileNotFoundError` when
adding a new file to `CONFIG` and you had to manually write a file with
help tag of the first section as placeholder. This change relieves you
of that need.
This introduces two new functions `vim.keymap.set` & `vim.keymap.del`
differences compared to regular set_keymap:
- remap is used as opposite of noremap. By default it's true for <Plug> keymaps and false for others.
- rhs can be lua function.
- mode can be a list of modes.
- replace_keycodes option for lua function expr maps. (Default: true)
- handles buffer specific keymaps
Examples:
```lua
vim.keymap.set('n', 'asdf', function() print("real lua function") end)
vim.keymap.set({'n', 'v'}, '<leader>lr', vim.lsp.buf.references, {buffer=true})
vim.keymap.set('n', '<leader>w', "<cmd>w<cr>", {silent = true, buffer = 5 })
vim.keymap.set('i', '<Tab>', function()
return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
end, {expr = true})
vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
vim.keymap.del('n', 'asdf')
vim.keymap.del({'n', 'i', 'v'}, '<leader>w', {buffer = 5 })
```
The spacing fix drew attention to a couple of places that were using
incorrect formatting such as the key listing for `nvim_open_win`, so
those were fixed too.
Continuation of https://github.com/neovim/neovim/pull/15202
A plugin like telescope could override it with a fancy implementation
and then users would get the telescope-ui within each plugin that
utilizes the vim.ui.select function.
There are some plugins which override the `textDocument/codeAction`
handler solely to provide a different UI. With custom client commands and
soon codeAction resolve support, it becomes more difficult to implement
the handler right - so having a dedicated way to override the picking
function will be useful.
## Overview
- Move vim.lsp.diagnostic to vim.diagnostic
- Refactor client ids to diagnostic namespaces
- Update tests
- Write/update documentation and function signatures
Currently, non-LSP diagnostics in Neovim must hook into the LSP subsystem. This
is what e.g. null-ls and nvim-lint do. This is necessary because none of the
diagnostic API is exposed separately from the LSP subsystem.
This commit addresses this by generalizing the diagnostic subsystem beyond the
scope of LSP. The `vim.lsp.diagnostic` module is now simply a specific
diagnostic producer and primarily maintains the interface between LSP clients
and the broader diagnostic API.
The current diagnostic API uses "client ids" which only makes sense in the
context of LSP. We replace "client ids" with standard API namespaces generated
from `nvim_create_namespace`.
This PR is *mostly* backward compatible (so long as plugins are only using the
publicly documented API): LSP diagnostics will continue to work as usual, as
will pseudo-LSP clients like null-ls and nvim-lint. However, the latter can now
use the new interface, which looks something like this:
```lua
-- The namespace *must* be given a name. Anonymous namespaces will not work with diagnostics
local ns = vim.api.nvim_create_namespace("foo")
-- Generate diagnostics
local diagnostics = generate_diagnostics()
-- Set diagnostics for the current buffer
vim.diagnostic.set(ns, diagnostics, bufnr)
```
Some public facing API utility methods were removed and internalized directly in `vim.diagnostic`:
* `vim.lsp.util.diagnostics_to_items`
## API Design
`vim.diagnostic` contains most of the same API as `vim.lsp.diagnostic` with
`client_id` simply replaced with `namespace`, with some differences:
* Generally speaking, functions that modify or add diagnostics require a namespace as their first argument, e.g.
```lua
vim.diagnostic.set({namespace}, {bufnr}, {diagnostics}[, {opts}])
```
while functions that read or query diagnostics do not (although in many cases one may be supplied optionally):
```lua
vim.diagnostic.get({bufnr}[, {namespace}])
```
* We use our own severity levels to decouple `vim.diagnostic` from LSP. These
are designed similarly to `vim.log.levels` and currently include:
```lua
vim.diagnostic.severity.ERROR
vim.diagnostic.severity.WARN
vim.diagnostic.severity.INFO
vim.diagnostic.severity.HINT
```
In practice, these match the LSP diagnostic severity levels exactly, but we
should treat this as an interface and not assume that they are the same. The
"translation" between the two severity types is handled transparently in
`vim.lsp.diagnostic`.
* The actual "diagnostic" data structure is: (**EDIT:** Updated 2021-09-09):
```lua
{
lnum = <number>,
col = <number>,
end_lnum = <number>,
end_col = <number>,
severity = <vim.diagnostic.severity>,
message = <string>
}
```
This differs from the LSP definition of a diagnostic, so we transform them in
the handler functions in vim.lsp.diagnostic.
## Configuration
The `vim.lsp.with` paradigm still works for configuring how LSP diagnostics are
displayed, but this is a specific use-case for the `publishDiagnostics` handler.
Configuration with `vim.diagnostic` is instead done with the
`vim.diagnostic.config` function:
```lua
vim.diagnostic.config({
virtual_text = true,
signs = false,
underline = true,
update_in_insert = true,
severity_sort = false,
}[, namespace])
```
(or alternatively passed directly to `set()` or `show()`.)
When the `namespace` argument is `nil`, settings are set globally (i.e. for
*all* diagnostic namespaces). This is what user's will typically use for their
local configuration. Diagnostic producers can also set configuration options for
their specific namespace, although this is generally discouraged in order to
respect the user's global settings. All of the values in the table passed to
`vim.diagnostic.config()` are resolved in the same way that they are in
`on_publish_diagnostics`; that is, the value can be a boolean, a table, or
a function:
```lua
vim.diagnostic.config({
virtual_text = function(namespace, bufnr)
-- Only enable virtual text in buffer 3
return bufnr == 3
end,
})
```
## Misc Notes
* `vim.diagnostic` currently depends on `vim.lsp.util` for floating window
previews. I think this is okay for now, although ideally we'd want to decouple
these completely.
