diff options
Diffstat (limited to 'runtime/doc/pi_health.txt')
| -rw-r--r-- | runtime/doc/pi_health.txt | 153 |
1 files changed, 111 insertions, 42 deletions
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index bb688770fc..179c1066cd 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -5,7 +5,7 @@ Author: TJ DeVries <devries.timothyj@gmail.com> Type |gO| to see the table of contents. ============================================================================== -Introduction *health* +Introduction *health* health.vim is a minimal framework to help with troubleshooting user configuration. Nvim ships with healthchecks for configuration, performance, @@ -18,65 +18,136 @@ To run the healthchecks, use this command: > Plugin authors are encouraged to write new healthchecks. |health-dev| ============================================================================== -Commands *health-commands* +Commands *health-commands* - *:checkhealth* *:CheckHealth* + *:checkhealth* *:CheckHealth* :checkhealth Run all healthchecks. - *E5009* - Nvim depends on |$VIMRUNTIME| and 'runtimepath' 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. + *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. :checkhealth {plugins} - Run healthcheck(s) for one or more plugins. E.g. to run - only the standard Nvim healthcheck: > + Run healthcheck(s) for one or more plugins. E.g. to run only + the standard Nvim healthcheck: > :checkhealth nvim -< To run the healthchecks for the "foo" and "bar" plugins - (assuming these plugins are on your 'runtimepath' and - they have implemented health#foo#check() and - health#bar#check(), respectively): > +< + To run the healthchecks for the "foo" and "bar" plugins + (assuming these plugins are on 'runtimepath' or 'packpath' and + they have implemented the Lua or Vimscript interface + require("foo.health").check() and health#bar#check(), + respectively): > :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` > + :checkhealth vim.lsp vim.treesitter + :checkhealth vim* +< ============================================================================== -Functions *health-functions* +Lua Functions *health-functions-lua* *health-lua* + +The Lua "health" module can be used to create new healthchecks (see also +|health-functions-vim|). To get started, simply use: > + local health = require('health') +< +health.report_start({name}) *health.report_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. + +health.report_info({msg}) *health.report_info()* + Reports an informational message. + +health.report_ok({msg}) *health.report_ok()* + Reports a "success" message. + +health.report_warn({msg} [, {advice}]) *health.report_warn()* + Reports a warning. {advice} is an optional List of suggestions. + +health.report_error({msg} [, {advice}]) *health.report_error()* + Reports an error. {advice} is an optional List of suggestions. + +============================================================================== +Create a Lua healthcheck *health-dev-lua* + +Healthchecks are functions that check the user environment, configuration, +etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. -health.vim functions are for creating new healthchecks. They mostly just do -some layout and formatting, to give users a consistent presentation. +To add a new healthcheck for your own plugin, simply define a Lua module in +your plugin that returns a table with a "check()" function. |:checkhealth| +will automatically find and invoke this function. -health#report_start({name}) *health#report_start* - Starts a new report. Most plugins should call this only once, but if +If your plugin is named "foo", then its healthcheck module should be a file in +one of these locations on 'runtimepath' or 'packpath': + - lua/foo/health/init.lua + - lua/foo/health.lua + +If your plugin provides a submodule named "bar" for which you want a separate +healthcheck, define the healthcheck at one of these locations on 'runtimepath' +or 'packpath': + - lua/foo/bar/health/init.lua + - lua/foo/bar/health.lua + +All submodules should return a Lua table containing the method `check()`. + +Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`, +replacing "foo" in the path with your plugin name: > + + local M = {} + local health = require("health") + + M.check = function() + health.report_start("my_plugin report") + -- make sure setup function parameters are ok + if check_setup() then + health.report_ok("Setup function is correct") + else + health.report_error("Setup function is incorrect") + end + -- do some more checking + -- ... + end + + return M + +============================================================================== +Vimscript Functions *health-functions-vimscript* *health-vimscript* + +health.vim functions are for creating new healthchecks. (See also +|health-functions-lua|) + +health#report_start({name}) *health#report_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. -health#report_info({msg}) *health#report_info* - Reports an informational message. +health#report_info({msg}) *health#report_info* + Reports an informational message. -health#report_ok({msg}) *health#report_ok* - Reports a "success" message. +health#report_ok({msg}) *health#report_ok* + Reports a "success" message. -health#report_warn({msg}, [{advice}]) *health#report_warn* +health#report_warn({msg} [, {advice}]) *health#report_warn* Reports a warning. {advice} is an optional List of suggestions. -health#report_error({msg}, [{advice}]) *health#report_error* +health#report_error({msg} [, {advice}]) *health#report_error* Reports an error. {advice} is an optional List of suggestions. -health#{plugin}#check() *health.user_checker* +health#{plugin}#check() *health.user_checker* Healthcheck function for {plugin}. Called by |:checkhealth| automatically. Example: > - function! health#my_plug#check() abort - silent call s:check_environment_vars() - silent call s:check_python_configuration() - endfunction + function! health#my_plug#check() abort + silent call s:check_environment_vars() + silent call s:check_python_configuration() + endfunction < - All output will be captured from the healthcheck. Use the - health#report_* functions so that your healthcheck has a format - consistent with the standard healthchecks. - ============================================================================== -Create a healthcheck *health-dev* +Create a healthcheck *health-dev-vim* Healthchecks are functions that check the user environment, configuration, etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. @@ -88,8 +159,8 @@ health#{plugin}#check() function in autoload/health/{plugin}.vim. If your plugin is named "foo", then its healthcheck function must be > health#foo#check() -defined in this file on 'runtimepath': > - autoload/health/foo.vim +defined in this file on 'runtimepath' or 'packpath': + - autoload/health/foo.vim Copy this sample code into autoload/health/foo.vim and replace "foo" with your plugin name: > @@ -97,7 +168,7 @@ plugin name: > call health#report_start('sanity checks') " perform arbitrary checks " ... - + if looks_good call health#report_ok('found required dependencies') else @@ -106,6 +177,4 @@ plugin name: > endif endfunction -============================================================================== - -vim:tw=78:ts=8:ft=help:fdm=marker +vim:et:tw=78:ts=8:ft=help:fdm=marker |