docs: extract health to its own file

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 ~
 

runtime/doc/editorconfig.txt

@@ -3,6 +3,8 @@
 
                             NVIM REFERENCE MANUAL
 
+                                       Type |gO| to see the table of contents.
+
 ==============================================================================
 EditorConfig integration                                        *editorconfig*
 

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:

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

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:

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

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

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