diff options
Diffstat (limited to 'runtime/doc/pi_health.txt')
| -rw-r--r-- | runtime/doc/pi_health.txt | 140 |
1 files changed, 42 insertions, 98 deletions
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index 04e04b5165..8a6437fdc8 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -7,11 +7,12 @@ Author: TJ DeVries <devries.timothyj@gmail.com> ============================================================================== Introduction *health* -health.vim is a minimal framework to help with troubleshooting user -configuration. Nvim ships with healthchecks for configuration, performance, -python support, ruby support, clipboard support, and more. +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 the healthchecks, use this command: > +To run all healthchecks, use: > :checkhealth < @@ -21,7 +22,7 @@ Plugin authors are encouraged to write new healthchecks. |health-dev| Commands *health-commands* *:checkhealth* *:CheckHealth* -:checkhealth Run all healthchecks. +:checkhealth Run all healthchecks. *E5009* Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to find the standard "runtime files" for syntax highlighting, @@ -35,23 +36,21 @@ Commands *health-commands* :checkhealth nvim < 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): > + (assuming they are on 'runtimepath' and they have implemented + the Lua `require("foo.health").check()` interface): > :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` > + 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* < ============================================================================== -Lua Functions *health-functions-lua* *health-lua* *vim.health* +Functions *health-functions* *vim.health* -The Lua "health" module can be used to create new healthchecks (see also -|health-functions-vim|). To get started, simply use: +The Lua "health" module can be used to create new healthchecks. To get started +see |health-dev|. vim.health.report_start({name}) *vim.health.report_start()* Starts a new report. Most plugins should call this only once, but if @@ -65,36 +64,43 @@ vim.health.report_ok({msg}) *vim.health.report_ok()* Reports a "success" message. vim.health.report_warn({msg} [, {advice}]) *vim.health.report_warn()* - Reports a warning. {advice} is an optional List of suggestions. + Reports a warning. {advice} is an optional list of suggestions to + present to the user. vim.health.report_error({msg} [, {advice}]) *vim.health.report_error()* - Reports an error. {advice} is an optional List of suggestions. + Reports an error. {advice} is an optional list of suggestions to + present to the user. ============================================================================== -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/. - -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. - -If your plugin is named "foo", then its healthcheck module should be a file in -one of these locations on 'runtimepath' or 'packpath': +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 provides a submodule named "bar" for which you want a separate -healthcheck, define the healthcheck at one of these locations on 'runtimepath' -or 'packpath': +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 submodules should return a Lua table containing the method `check()`. +All such health modules must return a Lua table containing a `check()` +function. -Copy this sample code into `lua/foo/health/init.lua` or `lua/foo/health.lua`, -replacing "foo" in the path with your plugin name: > +Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path +with your plugin name: > local M = {} @@ -102,9 +108,9 @@ replacing "foo" in the path with your plugin name: > vim.health.report_start("my_plugin report") -- make sure setup function parameters are ok if check_setup() then - vim.health.report_ok("Setup function is correct") + vim.health.report_ok("Setup is correct") else - vim.health.report_error("Setup function is incorrect") + vim.health.report_error("Setup is incorrect") end -- do some more checking -- ... @@ -112,67 +118,5 @@ replacing "foo" in the path with your plugin name: > 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_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. - -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 -< -============================================================================== -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/. - -To add a new healthcheck for your own plugin, simply define a -health#{plugin}#check() function in autoload/health/{plugin}.vim. -|:checkhealth| automatically finds and invokes such functions. - -If your plugin is named "foo", then its healthcheck function must be > - health#foo#check() - -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: > - function! health#foo#check() abort - call health#report_start('sanity checks') - " perform arbitrary checks - " ... - - if looks_good - call health#report_ok('found required dependencies') - else - call health#report_error('cannot find foo', - \ ['npm install --save foo']) - endif - endfunction vim:et:tw=78:ts=8:ft=help:fdm=marker |