kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-19 10:45:16 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: extract health to its own file

Browse Source
This commit is contained in:
dundargoc 2024-05-23 11:40:51 +02:00 committed by dundargoc
parent 4f431bb632
commit 6dc62c2e2b
8 changed files with 159 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
runtime/doc/develop.txt
View File

@ -159,6 +159,12 @@ DOCUMENTATION *dev-doc*
not "the user host terminal".
- Use "tui-" to prefix help tags related to the host terminal, and "TUI"
in prose if possible.
- Rough guidelines on where Lua documentation should end up:
- Nvim API functions `vim.api.nvim_*` should be in `api.txt`.
- If the module is big and not relevant to generic and lower-level Lua
functionality, then it's a strong candidate for separation. Example:
`treesitter.txt`
- Otherwise, add them to `lua.txt`
Documentation format ~

2
runtime/doc/editorconfig.txt
View File

@ -3,6 +3,8 @@
NVIM REFERENCE MANUAL
Type |gO| to see the table of contents.
==============================================================================
EditorConfig integration *editorconfig*

134
runtime/doc/health.txt Normal file
View File

@ -0,0 +1,134 @@
*health.txt* Nvim
NVIM REFERENCE MANUAL
Type |gO| to see the table of contents.
==============================================================================
Checkhealth *health*
health.vim is a minimal framework to help users troubleshoot configuration and
any other environment conditions that a plugin might care about. Nvim ships
with healthchecks for configuration, performance, python support, ruby
support, clipboard support, and more.
To run all healthchecks, use: >vim
:checkhealth
<
Plugin authors are encouraged to write new healthchecks. |health-dev|
Commands *health-commands*
*:che* *:checkhealth*
:che[ckhealth] Run all healthchecks.
*E5009*
Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
find the standard "runtime files" for syntax highlighting,
filetype-specific behavior, and standard plugins (including
:checkhealth). If the runtime files cannot be found then
those features will not work.
:che[ckhealth] {plugins}
Run healthcheck(s) for one or more plugins. E.g. to run only
the standard Nvim healthcheck: >vim
:checkhealth vim.health
<
To run the healthchecks for the "foo" and "bar" plugins
(assuming they are on 'runtimepath' and they have implemented
the Lua `require("foo.health").check()` interface): >vim
:checkhealth foo bar
<
To run healthchecks for Lua submodules, use dot notation or
"*" to refer to all submodules. For example Nvim provides
`vim.lsp` and `vim.treesitter`: >vim
:checkhealth vim.lsp vim.treesitter
:checkhealth vim*
<
Create a healthcheck *health-dev* *vim.health*
Healthchecks are functions that check the user environment, configuration, or
any other prerequisites that a plugin cares about. Nvim ships with
healthchecks in:
- $VIMRUNTIME/autoload/health/
- $VIMRUNTIME/lua/vim/lsp/health.lua
- $VIMRUNTIME/lua/vim/treesitter/health.lua
- and more...
To add a new healthcheck for your own plugin, simply create a "health.lua"
module on 'runtimepath' that returns a table with a "check()" function. Then
|:checkhealth| will automatically find and invoke the function.
For example if your plugin is named "foo", define your healthcheck module at
one of these locations (on 'runtimepath'):
- lua/foo/health/init.lua
- lua/foo/health.lua
If your plugin also provides a submodule named "bar" for which you want
a separate healthcheck, define the healthcheck at one of these locations:
- lua/foo/bar/health/init.lua
- lua/foo/bar/health.lua
All such health modules must return a Lua table containing a `check()`
function.
Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
with your plugin name: >lua
local M = {}
M.check = function()
vim.health.start("foo report")
-- make sure setup function parameters are ok
if check_setup() then
vim.health.ok("Setup is correct")
else
vim.health.error("Setup is incorrect")
end
-- do some more checking
-- ...
end
return M
error({msg}, {...}) *vim.health.error()*
Reports an error.
Parameters: ~
• {msg} (`string`)
• {...} (`string|string[]`) Optional advice
info({msg}) *vim.health.info()*
Reports an informational message.
Parameters: ~
• {msg} (`string`)
ok({msg}) *vim.health.ok()*
Reports a "success" message.
Parameters: ~
• {msg} (`string`)
start({name}) *vim.health.start()*
Starts a new report. Most plugins should call this only once, but if you
want different sections to appear in your report, call this once per
section.
Parameters: ~
• {name} (`string`)
warn({msg}, {...}) *vim.health.warn()*
Reports a warning.
Parameters: ~
• {msg} (`string`)
• {...} (`string|string[]`) Optional advice
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

1
runtime/doc/help.txt
View File

@ -114,6 +114,7 @@ API (EXTENSIBILITY/SCRIPTING/PLUGINS)
|vimscript-functions| Vimscript functions
|testing.txt| Vimscript testing functions
|remote-plugin| Nvim remote plugins
|health| Health checking
------------------------------------------------------------------------------
PROGRAMMING LANGUAGE SUPPORT

125
runtime/doc/lua.txt
View File

@ -4430,129 +4430,4 @@ tohtml.tohtml({winid}, {opt}) *tohtml.tohtml.tohtml()*
(`string[]`)
==============================================================================
Lua module: vim.health *vim.health*
health.vim is a minimal framework to help users troubleshoot configuration and
any other environment conditions that a plugin might care about. Nvim ships
with healthchecks for configuration, performance, python support, ruby
support, clipboard support, and more.
To run all healthchecks, use: >vim
:checkhealth
<
Plugin authors are encouraged to write new healthchecks. |health-dev|
Commands *health-commands*
*:che* *:checkhealth*
:che[ckhealth] Run all healthchecks.
*E5009*
Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
find the standard "runtime files" for syntax highlighting,
filetype-specific behavior, and standard plugins (including
:checkhealth). If the runtime files cannot be found then
those features will not work.
:che[ckhealth] {plugins}
Run healthcheck(s) for one or more plugins. E.g. to run only
the standard Nvim healthcheck: >vim
:checkhealth vim.health
<
To run the healthchecks for the "foo" and "bar" plugins
(assuming they are on 'runtimepath' and they have implemented
the Lua `require("foo.health").check()` interface): >vim
:checkhealth foo bar
<
To run healthchecks for Lua submodules, use dot notation or
"*" to refer to all submodules. For example Nvim provides
`vim.lsp` and `vim.treesitter`: >vim
:checkhealth vim.lsp vim.treesitter
:checkhealth vim*
<
Create a healthcheck *health-dev*
Healthchecks are functions that check the user environment, configuration, or
any other prerequisites that a plugin cares about. Nvim ships with
healthchecks in:
- $VIMRUNTIME/autoload/health/
- $VIMRUNTIME/lua/vim/lsp/health.lua
- $VIMRUNTIME/lua/vim/treesitter/health.lua
- and more...
To add a new healthcheck for your own plugin, simply create a "health.lua"
module on 'runtimepath' that returns a table with a "check()" function. Then
|:checkhealth| will automatically find and invoke the function.
For example if your plugin is named "foo", define your healthcheck module at
one of these locations (on 'runtimepath'):
- lua/foo/health/init.lua
- lua/foo/health.lua
If your plugin also provides a submodule named "bar" for which you want
a separate healthcheck, define the healthcheck at one of these locations:
- lua/foo/bar/health/init.lua
- lua/foo/bar/health.lua
All such health modules must return a Lua table containing a `check()`
function.
Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
with your plugin name: >lua
local M = {}
M.check = function()
vim.health.start("foo report")
-- make sure setup function parameters are ok
if check_setup() then
vim.health.ok("Setup is correct")
else
vim.health.error("Setup is incorrect")
end
-- do some more checking
-- ...
end
return M
vim.health.error({msg}, {...}) *vim.health.error()*
Reports an error.
Parameters: ~
• {msg} (`string`)
• {...} (`string|string[]`) Optional advice
vim.health.info({msg}) *vim.health.info()*
Reports an informational message.
Parameters: ~
• {msg} (`string`)
vim.health.ok({msg}) *vim.health.ok()*
Reports a "success" message.
Parameters: ~
• {msg} (`string`)
vim.health.start({name}) *vim.health.start()*
Starts a new report. Most plugins should call this only once, but if you
want different sections to appear in your report, call this once per
section.
Parameters: ~
• {name} (`string`)
vim.health.warn({msg}, {...}) *vim.health.warn()*
Reports a warning.
Parameters: ~
• {msg} (`string`)
• {...} (`string|string[]`) Optional advice
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

2
runtime/lua/vim/health.lua
View File

@ -39,7 +39,7 @@
--- :checkhealth vim*
--- <
---
--- Create a healthcheck *health-dev*
--- Create a healthcheck *health-dev* *vim.health*
---
--- Healthchecks are functions that check the user environment, configuration, or
--- any other prerequisites that a plugin cares about. Nvim ships with

1
scripts/gen_help_html.lua
View File

@ -1440,7 +1440,6 @@ function M.test_gen(help_dir)
-- Because gen() is slow (~30s), this test is limited to a few files.
{ 'help.txt', 'index.txt', 'nvim.txt' }
)
eq(3, #rv.helpfiles)
eq(0, rv.err_count, 'parse errors in :help docs')
eq({}, rv.invalid_links, 'invalid tags in :help docs')
end

17
scripts/gen_vimdoc.lua
View File

@ -162,7 +162,6 @@ local config = {
'snippet.lua',
'text.lua',
'tohtml.lua',
'health.lua',
},
files = {
'runtime/lua/vim/iter.lua',
@ -182,7 +181,6 @@ local config = {
'runtime/lua/vim/snippet.lua',
'runtime/lua/vim/text.lua',
'runtime/lua/vim/glob.lua',
'runtime/lua/vim/health.lua',
'runtime/lua/vim/_meta/builtin.lua',
'runtime/lua/vim/_meta/diff.lua',
'runtime/lua/vim/_meta/mpack.lua',
@ -363,6 +361,21 @@ local config = {
fun.name = vim.split(fun.name, '.', { plain = true })[2]
end,
},
health = {
filename = 'health.txt',
files = {
'runtime/lua/vim/health.lua',
},
section_order = {
'health.lua',
},
section_fmt = function(_name)
return 'Checkhealth'
end,
helptag_fmt = function(name)
return name:lower()
end,
},
}
--- @param ty string