From 171b6df1ad1bb3ee7ef115191ae5e473004b2872 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Wed, 2 Apr 2025 06:33:41 -0700
Subject: fix(docgen): :help (vimdoc) format #3683

followup to #3675
---
 scripts/docgen.lua        | 29 +++++++++++------------------
 scripts/docs_template.md  |  5 -----
 scripts/docs_template.txt |  9 +++++++--
 3 files changed, 18 insertions(+), 25 deletions(-)

(limited to 'scripts')

diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index bab89851..2f7d114e 100755
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -61,37 +61,32 @@ local function readfile(path)
   return io.open(path):read '*a'
 end
 
-local function relpath(from, to)
-  return to:gsub('^' .. vim.pesc(from) .. '/', '')
-end
-
-local lsp_section_template_txt = [[
-==============================================================================
-{{tagline}}
+local section_template_txt = [[
+------------------------------------------------------------------------------
+{{config_name}}
 
 {{preamble}}
 
-Snippet to enable the language server:
-```lua
-require'lspconfig'.{{config_name}}.setup{}
-```
+Snippet to enable the language server: >lua
+  require'lspconfig'.{{config_name}}.setup{}
+
 {{commands}}
 Default config:
 {{default_values}}
 
 ]]
 
-local lsp_section_template_md = [[
+local section_template_md = [[
 ## {{config_name}}
 
 {{preamble}}
 
-**Snippet to enable the language server:**
+Snippet to enable the language server:
 ```lua
 require'lspconfig'.{{config_name}}.setup{}
 ```
 {{commands}}
-**Default config:**
+Default config:
 {{default_values}}
 
 ---
@@ -130,8 +125,6 @@ local function make_lsp_sections(is_markdown)
         preamble = '',
         commands = '',
         default_values = '',
-        tagline = is_markdown and ''
-          or string.format('%s                                                       *%s*', config_name, config_name),
       }
 
       params.commands = make_section(0, '\n', {
@@ -173,7 +166,7 @@ local function make_lsp_sections(is_markdown)
                 end
               end
               io.close(file)
-              local config_relpath = relpath(root, config_file)
+              local config_relpath = vim.fs.relpath(root, config_file)
 
               -- XXX: "../" because the path is outside of the doc/ dir.
               return ('- `%s` source (use "gF" to visit): [../%s:%d](../%s#L%d)'):format(
@@ -281,7 +274,7 @@ local function make_lsp_sections(is_markdown)
         params.preamble = vim.trim(table.concat(preamble_parts, '\n'))
       end
 
-      local template_used = is_markdown and lsp_section_template_md or lsp_section_template_txt
+      local template_used = is_markdown and section_template_md or section_template_txt
       return template(template_used, params)
     end)
   )
diff --git a/scripts/docs_template.md b/scripts/docs_template.md
index cb25a45c..9ae0dd7a 100644
--- a/scripts/docs_template.md
+++ b/scripts/docs_template.md
@@ -1,5 +1,4 @@
 # LSP configs
-<!-- *lspconfig-all* *lspconfig-server-configurations* -->
 
 LSP configurations provided by nvim-lspconfig are listed below. This
 documentation is autogenerated from the Lua files. You can view this file in
@@ -8,7 +7,3 @@ Nvim by running `:help lspconfig-all`.
 {{implemented_servers_list}}
 
 {{lsp_server_details}}
-
-<!--
-vim:ft=markdown
--->
diff --git a/scripts/docs_template.txt b/scripts/docs_template.txt
index c3aa7deb..826f52be 100644
--- a/scripts/docs_template.txt
+++ b/scripts/docs_template.txt
@@ -1,9 +1,14 @@
-*lspconfig-all*                              *lspconfig-server-configurations*
+*lspconfig-all*
 
 LSP configurations provided by nvim-lspconfig are listed below.
 
+                                      Type |gO| to see the table of contents.
+
 ==============================================================================
+LSP configs
 
 {{lsp_server_details}}
 
-" vim:tw=78:ft=help:norl:expandtab:sw=4
+==============================================================================
+
+ vim:tw=78:ft=help:norl:expandtab:sw=4
-- 
cgit v1.2.3-70-g09d2