feat(docs): "yxx" runs Lua/Vimscript code examples #31904

`yxx` in Normal mode over a Lua or Vimscript code block section will execute the code.

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

9 files changed, 70 insertions, 12 deletions

diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index 46b3ab507d..f7009aebfe 100644
--- a/runtime/doc/helphelp.txt
+++ b/runtime/doc/helphelp.txt
@@ -193,6 +193,7 @@ Jump to specific subjects by using tags.  This can be done in two ways:
 
 Use CTRL-T or CTRL-O to jump back.
 Use ":q" to close the help window.
+Use `yxx` to execute the current Lua/Vimscript code block.
 
 If there are several matches for an item you are looking for, this is how you
 can jump to each one of them:
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6547a76f56..6386240f07 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -161,7 +161,7 @@ languages like Python and C#. Example: >lua
     local func_with_opts = function(opts)
         local will_do_foo = opts.foo
         local filename = opts.filename
-        ...
+        -- ...
     end
 
     func_with_opts { foo = true, filename = "hello.world" }
@@ -2428,7 +2428,7 @@ vim.validate({name}, {value}, {validator}, {optional}, {message})
          function vim.startswith(s, prefix)
           vim.validate('s', s, 'string')
           vim.validate('prefix', prefix, 'string')
-          ...
+          -- ...
         end
 <
     2. `vim.validate(spec)` (deprecated) where `spec` is of type
@@ -2442,7 +2442,7 @@ vim.validate({name}, {value}, {validator}, {optional}, {message})
             age={age, 'number'},
             hobbies={hobbies, 'table'},
           }
-          ...
+          -- ...
         end
 <
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 960b6f05f9..e1824e068d 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -276,6 +276,7 @@ LUA
   supporting two new parameters, `encoding` and `strict_indexing`.
 • |vim.json.encode()| has an option to enable forward slash escaping
 • |vim.fs.abspath()| converts paths to absolute paths.
+• Lua and vimscript code examples in docs can now be run using `yxx`.
 
 OPTIONS
 
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index ff8e3a976f..7d79669ed8 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -165,8 +165,8 @@ directory indicated in the request. >lua
     end
   })
 
-To try it out, select the above code and source it with `:'<,'>lua`, then run
-this command in a :terminal buffer: >
+To try it out, select the above code and source it with `:'<,'>lua` (or
+`yxx`), then run this command in a :terminal buffer: >
 
     printf "\033]7;file://./foo/bar\033\\"
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 28fe943359..538435e5e8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -1336,7 +1336,7 @@ parse({lang}, {query})                          *vim.treesitter.query.parse()*
       `info.captures`).
     • `info.patterns`: information about predicates.
 
-    Example (select the code then run `:'<,'>lua` to try it): >lua
+    Example (to try it, use `yxx` or select the code then run `:'<,'>lua`): >lua
         local query = vim.treesitter.query.parse('vimdoc', [[
           ; query
           ((h1) @str
@@ -1422,7 +1422,7 @@ Query:iter_matches({node}, {source}, {start}, {stop}, {opts})
               -- `node` was captured by the `name` capture in the match
 
               local node_data = metadata[id] -- Node level metadata
-              ... use the info here ...
+              -- ... use the info here ...
             end
           end
         end
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 6074931565..611e820cab 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -554,6 +554,11 @@ gO			Show a filetype-specific, navigable "outline" of the
 							*:sl!* *:sleep!*
 :[N]sl[eep]! [N][m]	Same as above, but hide the cursor.
 
+							*yxx*
+yxx			Executes the current code block.
+
+			Works in |help| buffers.
+
 ==============================================================================
 2. Using Vim like less or more					*less*
 
diff --git a/runtime/ftplugin/help.lua b/runtime/ftplugin/help.lua
index 8d991be0e4..689a4db408 100644
--- a/runtime/ftplugin/help.lua
+++ b/runtime/ftplugin/help.lua
@@ -31,5 +31,56 @@ vim.keymap.set('n', 'gO', function()
   require('vim.vimhelp').show_toc()
 end, { buffer = 0, silent = true })
 
-vim.b.undo_ftplugin = (vim.b.undo_ftplugin or '') .. '\n exe "nunmap <buffer> gO"'
+-- Add "runnables" for Lua/Vimscript code examples.
+---@type table<integer, { lang: string, code: string }>
+local code_blocks = {}
+local tree = vim.treesitter.get_parser():parse()[1]
+local query = vim.treesitter.query.parse(
+  'vimdoc',
+  [[
+  (codeblock
+    (language) @_lang
+    .
+    (code) @code
+    (#any-of? @_lang "lua" "vim")
+    (#set! @code lang @_lang))
+]]
+)
+local run_message_ns = vim.api.nvim_create_namespace('vimdoc/run_message')
+
+vim.api.nvim_buf_clear_namespace(0, run_message_ns, 0, -1)
+for _, match, metadata in query:iter_matches(tree:root(), 0, 0, -1) do
+  for id, nodes in pairs(match) do
+    local name = query.captures[id]
+    local node = nodes[1]
+    local start, _, end_ = node:parent():range() --[[@as integer]]
+
+    if name == 'code' then
+      vim.api.nvim_buf_set_extmark(0, run_message_ns, start, 0, {
+        virt_text = { { 'Run with `yxx`', 'LspCodeLens' } },
+      })
+      local code = vim.treesitter.get_node_text(node, 0)
+      local lang_node = match[metadata[id].lang][1] --[[@as TSNode]]
+      local lang = vim.treesitter.get_node_text(lang_node, 0)
+      for i = start + 1, end_ do
+        code_blocks[i] = { lang = lang, code = code }
+      end
+    end
+  end
+end
+
+vim.keymap.set('n', 'yxx', function()
+  local pos = vim.api.nvim_win_get_cursor(0)[1]
+  local code_block = code_blocks[pos]
+  if not code_block then
+    vim.print('No code block found')
+  elseif code_block.lang == 'lua' then
+    vim.cmd.lua(code_block.code)
+  elseif code_block.lang == 'vim' then
+    vim.cmd(code_block.code)
+  end
+end, { buffer = true })
+
+vim.b.undo_ftplugin = (vim.b.undo_ftplugin or '')
+  .. '\n exe "nunmap <buffer> gO" | exe "nunmap <buffer> yxx"'
 vim.b.undo_ftplugin = vim.b.undo_ftplugin .. ' | call v:lua.vim.treesitter.stop()'
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 24c3f243e5..02b12490af 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -959,7 +959,7 @@ do
   ---       function vim.startswith(s, prefix)
   ---         vim.validate('s', s, 'string')
   ---         vim.validate('prefix', prefix, 'string')
-  ---         ...
+  ---         -- ...
   ---       end
   ---     ```
   ---
@@ -979,7 +979,7 @@ do
   ---           age={age, 'number'},
   ---           hobbies={hobbies, 'table'},
   ---         }
-  ---         ...
+  ---         -- ...
   ---       end
   ---     ```
   ---
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index 1fc001b39f..b9bcbe9a80 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -292,7 +292,7 @@ end)
 ---   - `captures`: a list of unique capture names defined in the query (alias: `info.captures`).
 ---   - `info.patterns`: information about predicates.
 ---
---- Example (select the code then run `:'<,'>lua` to try it):
+--- Example (to try it, use `yxx` or select the code then run `:'<,'>lua`):
 --- ```lua
 --- local query = vim.treesitter.query.parse('vimdoc', [[
 ---   ; query
@@ -983,7 +983,7 @@ end
 ---       -- `node` was captured by the `name` capture in the match
 ---
 ---       local node_data = metadata[id] -- Node level metadata
----       ... use the info here ...
+---       -- ... use the info here ...
 ---     end
 ---   end
 --- end