diff options
| -rw-r--r-- | runtime/doc/develop.txt | 6 | ||||
| -rw-r--r-- | runtime/doc/editorconfig.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/health.txt | 134 | ||||
| -rw-r--r-- | runtime/doc/help.txt | 1 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 125 | ||||
| -rw-r--r-- | runtime/lua/vim/health.lua | 2 | ||||
| -rw-r--r-- | scripts/gen_help_html.lua | 1 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.lua | 17 |
8 files changed, 159 insertions, 129 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index adbe4eeeff..d7837dc2fe 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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 ~ diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt index aa4e150862..0b20c77801 100644 --- a/runtime/doc/editorconfig.txt +++ b/runtime/doc/editorconfig.txt @@ -3,6 +3,8 @@ NVIM REFERENCE MANUAL + Type |gO| to see the table of contents. + ============================================================================== EditorConfig integration *editorconfig* diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt new file mode 100644 index 0000000000..e879f11351 --- /dev/null +++ b/runtime/doc/health.txt @@ -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: diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index f2deac3cd8..43f80101ed 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -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 diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 76a6bc0801..fccda177d2 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -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: diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua index 263a6ec85f..2417709ea2 100644 --- a/runtime/lua/vim/health.lua +++ b/runtime/lua/vim/health.lua @@ -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 diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua index b61f01f124..cdfb85bde6 100644 --- a/scripts/gen_help_html.lua +++ b/scripts/gen_help_html.lua @@ -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 diff --git a/scripts/gen_vimdoc.lua b/scripts/gen_vimdoc.lua index eea5688621..9c6225efc3 100755 --- a/scripts/gen_vimdoc.lua +++ b/scripts/gen_vimdoc.lua @@ -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 |