fix(docs): handle config errors, document rename #4192

Problem:
If a config throws an error it fails the entire doc generation.

Solution:
Handle config error in docgen. Unfortunately, this doesn't show the
error message, it shows:

    loop or previous error loading module 'lsp.volar'

instead of the actual `error('…')` message.

So meanwhile, document the current deprecation/rename pattern and use
`vim.notify()` instead.

5 files changed, 44 insertions, 41 deletions

diff --git a/.github/workflows/problem_matchers/selene.json b/.github/workflows/problem_matchers/selene.json
deleted file mode 100644
index 4bbf24f3..00000000
--- a/.github/workflows/problem_matchers/selene.json
+++ /dev/null
@@ -1,30 +0,0 @@
-{
-  "problemMatcher": [
-    {
-      "owner": "selene-error",
-      "severity": "error",
-      "pattern": [
-        {
-          "regexp": "^([^:]+):(\\d+):(\\d+):\\serror(.*)$",
-          "file": 1,
-          "line": 2,
-          "column": 3,
-          "message": 4
-        }
-      ]
-    },
-    {
-      "owner": "selene-warning",
-      "severity": "warning",
-      "pattern": [
-        {
-          "regexp": "^([^:]+):(\\d+):(\\d+):\\swarning(.*)$",
-          "file": 1,
-          "line": 2,
-          "column": 3,
-          "message": 4
-        }
-      ]
-    }
-  ]
-}
diff --git a/.gitignore b/.gitignore
index a928eeda..9b959405 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,2 @@
-.luacheckcache
 neovim
 doc/tags
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 715bf13f..2dca9d81 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -125,6 +125,21 @@ return {
 }
 ```
 
+## Rename or deprecate a config
+
+If a config needs to be renamed or deprecated, changes its contents like this:
+
+```lua
+---@brief
+---
+--- Renamed to [vsrocq](#vsrocq)
+
+vim.deprecate('vscoqtop', 'vsrocq', '2.0.0', 'nvim-lspconfig', false)
+
+---@type vim.lsp.Config
+return vim.lsp.config.vsrocq
+```
+
 ## Commit style
 
 Follow the Neovim core [commit message guidelines](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#commit-messages). Examples:
@@ -146,10 +161,9 @@ Follow the Neovim core [commit message guidelines](https://github.com/neovim/neo
 
 ## Lint
 
-PRs are checked with the following software:
-- [luacheck](https://github.com/luarocks/luacheck#installation)
+PRs are checked with the following analyzers:
+- [luals](https://github.com/LuaLS/lua-language-server)
 - [stylua](https://github.com/JohnnyMorganz/StyLua).
-- [selene](https://github.com/Kampfkarren/selene)
 
 To run the linter locally:
 
@@ -166,4 +180,4 @@ Do not modify `configs.md` directly.
 To preview the generated `configs.md` locally, run `scripts/docgen.lua` from
 `nvim` (from the project root):
 
-    nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
+    HOME=./ nvim --clean -R -Es -V1 +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
diff --git a/lsp/vscoqtop.lua b/lsp/vscoqtop.lua
index 41b38eb4..78186c51 100644
--- a/lsp/vscoqtop.lua
+++ b/lsp/vscoqtop.lua
@@ -1,6 +1,8 @@
 ---@brief
 ---
---- https://github.com/coq-community/vscoq
+--- Renamed to [vsrocq](#vsrocq)
+
+vim.deprecate('vscoqtop', 'vsrocq', '2.0.0', 'nvim-lspconfig', false)
 
 ---@type vim.lsp.Config
-error("The 'vscoqtop' config has been renamed to 'vsrocq'.")
+return vim.lsp.config.vsrocq
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index 613417b1..e9673b34 100755
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -1,4 +1,9 @@
 #!/usr/bin/env -S nvim -l
+
+-- Usage:
+--
+--    HOME=./ nvim --clean -R -Es -V1 +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
+
 local root = vim.trim(vim.system({ 'git', 'rev-parse', '--show-toplevel' }):wait().stdout)
 vim.opt.rtp:append(root)
 
@@ -44,6 +49,7 @@ local function make_parts(fns)
   end))
 end
 
+--- @return string
 local function make_section(indentlvl, sep, parts)
   local flat = make_parts(parts)
   if not flat or #flat == 0 then
@@ -88,6 +94,8 @@ Default config:
 ]]
 
 --- Converts markdown "```" codeblock to vimdoc format.
+---
+--- @return string
 local function codeblock_to_vimdoc(doc)
   local function make_fn(before, extra)
     return function(lang, code)
@@ -112,6 +120,8 @@ local function codeblock_to_vimdoc(doc)
 end
 
 --- Gets docstring by looking for "@brief" in a Lua code docstring.
+---
+--- @return string
 local function extract_brief(text, is_markdown)
   local doc = text:match('%-%-+ *%@brief.-(\n%-%-.*)')
   if not doc then
@@ -133,15 +143,24 @@ local function extract_brief(text, is_markdown)
 end
 
 local function make_lsp_section(config_sections, config_name, config_file, is_markdown)
-  local config = require('lsp.' .. config_name)
-  local docstring = extract_brief(readfile(config_file), is_markdown)
+  local t = is_markdown and section_template_md or section_template_txt
   local params = {
     config_name = config_name,
-    preamble = docstring,
+    preamble = '',
     commands = '',
     default_values = '',
   }
 
+  local ok, config = pcall(require, 'lsp.' .. config_name)
+  -- If the config throws an error (e.g. "renamed to …"), just show the error message.
+  if not ok then
+    params.preamble = config
+    table.insert(config_sections, template(t, params))
+    return
+  end
+
+  params.preamble = extract_brief(readfile(config_file), is_markdown)
+
   -- TODO: get commands by parsing `nvim_buf_create_user_command` calls.
   params.commands = make_section(0, '\n', {
     function()
@@ -193,7 +212,6 @@ local function make_lsp_section(config_sections, config_name, config_file, is_ma
     end,
   }) .. (is_markdown and '' or '\n<') -- Workaround tree-sitter-vimdoc bug.
 
-  local t = is_markdown and section_template_md or section_template_txt
   table.insert(config_sections, template(t, params))
 end