CheckHealth

- Use execute() instead of redir
- Fixed logic on suboptimal pyenv/virtualenv checks.
- Move system calls from strings to lists. Fixes #5218
- Add highlighting
- Automatically discover health checkers
- Add tests

Helped-by: Shougo Matsushita <Shougo.Matsu@gmail.com>
Helped-by: Tommy Allen <tommy@esdf.io>

Closes #4932

2 files changed, 146 insertions, 8 deletions

diff --git a/runtime/doc/pi_health.txt b/runtime/doc/pi_health.txt
new file mode 100644
index 0000000000..d61c42bc06
--- /dev/null
+++ b/runtime/doc/pi_health.txt
@@ -0,0 +1,146 @@
+*pi_health.txt*   Check the status of your Neovim system
+
+Author: TJ DeVries <devries.timothyj@gmail.com>
+
+==============================================================================
+1. Contents					 *health.vim-contents*
+
+	1. Contents				: |health.vim-contents|
+	2. Health.vim introduction		: |health.vim-intro|
+	3. Health.vim manual			: |health.vim-manual|
+		3.1 Health.vim commands		: |health.vim-commands|
+	4. Making a new checker			: |health.vim-checkers|
+
+==============================================================================
+2. Health.vim introduction			*health.vim-intro*
+
+Debugging common issues is a time consuming task that many developers would
+like to eliminate, and where elimination is impossible, minimize. Many common
+questions and difficulties could be answered by a simple check of an
+environment variable or a setting that the user has made. However, even with
+FAQs and other manuals, it can be difficult to suggest the path a user should
+take without knowing some information about their system.
+
+Health.vim aims to solve this problem in two ways for both core and plugin
+maintainers.
+
+The way this is done is to provide an interface that users will know to check
+first before posting question in the issue tracker, dev channels, etc.  This
+is similar to how |:help| functions currently. The user experiencing
+difficulty can run |:CheckHealth| to view the status of one's system.
+
+The aim of |:CheckHealth| is two-fold.
+
+The first aim is to provide maintainers with an overview of the user's working
+environment. This skips large amounts of time where the maintainer must
+instruct the user on which steps to take to get debug information, and allows
+the maintainer to extend existing health scripts as more helpful debug
+information is found.
+
+The second aim is to provide maintainers a way of automating the answering of
+frequently encountered question. A common occurrence with Neovim is that the
+user has not installed the necessary Python modules to interact with Python
+remote plugins. A simple check of whether the Neovim remote plugin is
+installed can lead to a suggestion of >
+
+	You have not installed the Neovim Python module
+	You might want to try `$ pip install Neovim`
+
+< 
+With these possibilities, it allows the maintainer of a plugin to spend more
+time on active development, rather than trying to spend time on debugging
+common issues many times.
+
+==============================================================================
+3. Health.vim manual					*health.vim-manual*
+
+3.1 Commands
+------------
+
+:CheckHealth[!]						*:CheckHealth*
+	Run all health checkers found in g:health_checkers
+
+	It will check your setup for common problems that may be keeping a
+	plugin from functioning correctly.  Include the output of this command
+	in bug reports to help reduce the amount of time it takes to address
+	your issue.  With "!" the output will be placed in a new buffer which
+	can make it easier to save to a file or copy to the clipboard.
+
+
+3.2 Functions						*health.functions*
+-------------
+
+3.2.1 Report Functions					*health.report_functions*
+----------------------
+
+The |health.report_functions| are used by the plugin maintainer to remove the
+hassle of formatting multiple different levels of output. Not only does it
+remove the hassle of formatting, but it also provides users with a consistent
+interface for viewing the health information about the system.
+
+These functions are also expected to have the capability to produce output in
+multiple different formats. For example, if parsing of the results were to be
+done by a remote plugin, the results could be output in a valid JSON format
+and then the remote plugin could parse the results easily.
+
+health#report_start({name})				*health.funcs.report_start*
+	Start a report section.  It should represent a general area of tests
+	that can be understood from the argument {name} To start a new report
+	section, use this function again
+
+health#report_info({msg})				*health.funcs.report_info*
+	Use {msg} to report information in the current section
+
+health#report_ok({msg})					*health.funcs.report_ok*
+	Use {msg} to represent the check that has passed
+
+health#report_warn({msg}, ...)				*health.funcs.report_warn*
+	Use {msg} to represent a failed health check and optionally a list of
+	suggestions on how to fix it.
+
+health#report_error({msg}, ...)				*health.funcs.report_error*
+	Use {msg} to represent a critically failed health check and optionally
+	a list of suggestions on how to fix it.
+
+3.3 User Functions					*health.user_functions*
+------------------
+
+health#{my_plug}#check()				*health.user_checker*
+	A user defined function to run all of the checks that are required for
+	either debugging or suggestion making. An example might be something
+	like: >
+
+	function! health#my_plug#check() abort
+		silent call s:check_environment_vars()
+		silent call s:check_python_configuration()
+	endfunction
+<
+	This function will be found, sourced, and automatically called when
+	the user invokes |:CheckHealth|.
+
+	All output will be captured from the health checker. It is recommended
+	that the plugin maintainer uses the calls described in
+	|health.report_functions|. The benefits these functions provide are
+	described in the same section.
+
+
+==============================================================================
+4. Making a new checker				*health.vim-checkers*
+
+Health checkers are the scripts that check the health of the system. Neovim
+has built in checkers, which can be found in `runtime/autoload/health/`. To
+add a checker for a plugin, add a `health` folder in the `autoload` directory
+of your plugin. It is then suggested that the name of your script be
+`{plug_name}.vim`. For example, the health checker for `my_plug` might be
+placed in: >
+
+	$PLUGIN_BASE/autoload/health/my_plug.vim
+>
+
+Inside this script, a function must be specified to run. This function is
+described in |health.user_checker|.
+
+
+==============================================================================
+
+vim:tw=78:ts=8:ft=help:fdm=marker
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index 7380fb9346..63dbb00896 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -79,14 +79,6 @@ TROUBLESHOOTING					*python-trouble*
 If you have trouble with a plugin that uses the `neovim` Python client, use
 the |:CheckHealth| command to diagnose your setup.
 
-								 *:CheckHealth*
-:CheckHealth[!]	  Check your setup for common problems that may be keeping a
-		  plugin from functioning correctly.  Include the output of
-		  this command in bug reports to help reduce the amount of
-		  time it takes to address your issue.  With "!" the output
-		  will be placed in a new buffer which can make it easier to
-		  save to a file or copy to the clipboard.
-
 ==============================================================================
 Ruby integration		    	      *provider-ruby*