diff options
Diffstat (limited to 'runtime/doc/pi_health.txt')
| -rw-r--r-- | runtime/doc/pi_health.txt | 112 |
1 files changed, 48 insertions, 64 deletions
diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt index 69833103d1..bb688770fc 100644 --- a/runtime/doc/pi_health.txt +++ b/runtime/doc/pi_health.txt @@ -2,56 +2,45 @@ Author: TJ DeVries <devries.timothyj@gmail.com> -============================================================================== -1. Introduction |health.vim-intro| -2. Commands and functions |health.vim-manual| -3. Create a healthcheck |health.vim-dev| + Type |gO| to see the table of contents. ============================================================================== -Introduction *healthcheck* *health.vim-intro* +Introduction *health* -Troubleshooting user configuration problems is a time-consuming task that -developers want to minimize. health.vim provides a simple framework for plugin -authors to hook into, and for users to invoke, to check and report the user's -configuration and environment. Type this command to try it: > +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. - :CheckHealth -< -For example, some users have broken or unusual Python setups, which breaks the -|:python| command. |:CheckHealth| detects several common Python configuration -problems and reports them. If the Neovim Python module is not installed, it -shows a warning: > +To run the healthchecks, use this command: > - You have not installed the Neovim Python module - You might want to try `pip install Neovim` -< -Plugin authors are encouraged to add healthchecks, see |health.vim-dev|. + :checkhealth +< +Plugin authors are encouraged to write new healthchecks. |health-dev| ============================================================================== -Commands and functions *health.vim-manual* - -Commands ------------------------------------------------------------------------------- - *:CheckHealth* -:CheckHealth Run all healthchecks and show the output in a new - tabpage. These healthchecks are included by default: - - python2 - - python3 - - ruby - - remote plugin - -:CheckHealth {plugins} - Run healthchecks for one or more plugins. E.g. to run +Commands *health-commands* + + *: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. + +:checkhealth {plugins} + Run healthcheck(s) for one or more plugins. E.g. to run only the standard Nvim healthcheck: > - :CheckHealth nvim + :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): > - :CheckHealth foo bar + :checkhealth foo bar < -Functions ------------------------------------------------------------------------------- +============================================================================== +Functions *health-functions* health.vim functions are for creating new healthchecks. They mostly just do some layout and formatting, to give users a consistent presentation. @@ -62,54 +51,49 @@ health#report_start({name}) *health#report_start* per section. health#report_info({msg}) *health#report_info* - Displays an informational message. + Reports an informational message. health#report_ok({msg}) *health#report_ok* - Displays a "success" message. + Reports a "success" message. -health#report_warn({msg}, [{suggestions}]) *health#report_warn* - Displays a warning. {suggestions} is an optional List of suggestions. +health#report_warn({msg}, [{advice}]) *health#report_warn* + Reports a warning. {advice} is an optional List of suggestions. -health#report_error({msg}, [{suggestions}]) *health#report_error* - Displays an error. {suggestions} 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* - This is the form of a healthcheck definition. Call the above functions - from this function, then |:CheckHealth| does the rest. Example: > + 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 < - The function will be found and called automatically when the user - invokes |:CheckHealth|. - 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.vim-dev* +Create a healthcheck *health-dev* -Healthchecks are functions that check the health of the system. Neovim has -built-in checkers, found in $VIMRUNTIME/autoload/health/. +Healthchecks are functions that check the user environment, configuration, +etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/. -To add a new checker for your own plugin, simply define a +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. +|:checkhealth| automatically finds and invokes such functions. -If your plugin is named "jslint", then its healthcheck function must be > +If your plugin is named "foo", then its healthcheck function must be > + health#foo#check() - health#jslint#check() -< defined in this file on 'runtimepath': > + autoload/health/foo.vim - autoload/health/jslint.vim -< -Here's a sample to get started: > - - function! health#jslint#check() abort +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 " ... @@ -117,11 +101,11 @@ Here's a sample to get started: > if looks_good call health#report_ok('found required dependencies') else - call health#report_error('cannot find jslint', - \ ['npm install --save jslint']) + call health#report_error('cannot find foo', + \ ['npm install --save foo']) endif endfunction -< + ============================================================================== vim:tw=78:ts=8:ft=help:fdm=marker |