fix(help): workaround plugin/users overwritting tags (#1512)

Most plugin managers run :helptags in the plugin, which silently
overwrites the existing doc/tags. this is an issue for us since lspconfig
is manipulating the tags file to point to servers_configurations.md

Instead create a markdown comment with the name of the wanted tag and
make a copy in the repository of servers_configurations.md to
server_configurations.txt. Now when :helptags runs it finds the txt file
and generates the appropriate tag.

The advantage is this solution should work in all platforms, it also
removes lines from docgen CI.

.github/workflows/close-config-changes.yml

@@ -14,7 +14,7 @@ jobs:
           fetch-depth: 0
           ref: ${{ github.event.pull_request.head.sha }}
       - run: |
-          if ! git diff origin/$GITHUB_BASE_REF...$(git branch --show-current) --exit-code -- doc/server_configurations.md; then
+          if ! git diff origin/$GITHUB_BASE_REF...$(git branch --show-current) --exit-code -- doc/server_configurations.md doc/server_configurations.txt; then
             gh pr close $PR_NUMBER
             gh pr comment $PR_NUMBER --body "This pull request has been automatically closed. Changes to server_configurations.md aren't allowed - edit the lua source file instead. Consult https://github.com/neovim/nvim-lspconfig/blob/master/CONTRIBUTING.md#generating-docs."
             exit 1

.github/workflows/codespell.yml

@@ -18,4 +18,4 @@ jobs:
           pip install codespell
       - name: Use codespell
         run: |
-          codespell --quiet-level=2 --check-hidden --skip=./doc/server_configurations.md --ignore-words=.codespellignorewords || exit
+          codespell --quiet-level=2 --check-hidden --skip=./doc/server_configurations.md,./doc/server_configurations.txt --ignore-words=.codespellignorewords || exit

.github/workflows/docgen.yml

@@ -27,6 +27,6 @@ jobs:
       run: |
         git config user.name github-actions
         git config user.email github-actions@github.com
-        git add doc/server_configurations.md
+        git add doc/server_configurations.md doc/server_configurations.txt
         # Only commit and push if we have changes
         git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)

.gitignore

@@ -1,2 +1,3 @@
 .luacheckcache
 neovim
+doc/tags

doc/tags

@@ -1,21 +0,0 @@
-lspconfig	lspconfig.txt	/*lspconfig*
-lspconfig-adding-servers	lspconfig.txt	/*lspconfig-adding-servers*
-lspconfig-commands	lspconfig.txt	/*lspconfig-commands*
-lspconfig-completion	lspconfig.txt	/*lspconfig-completion*
-lspconfig-configurations	lspconfig.txt	/*lspconfig-configurations*
-lspconfig-debugging	lspconfig.txt	/*lspconfig-debugging*
-lspconfig-global-defaults	lspconfig.txt	/*lspconfig-global-defaults*
-lspconfig-keybindings	lspconfig.txt	/*lspconfig-keybindings*
-lspconfig-logging	lspconfig.txt	/*lspconfig-logging*
-lspconfig-lsp	lspconfig.txt	/*lspconfig-lsp*
-lspconfig-quickstart	lspconfig.txt	/*lspconfig-quickstart*
-lspconfig-root-advanced	lspconfig.txt	/*lspconfig-root-advanced*
-lspconfig-root-composition	lspconfig.txt	/*lspconfig-root-composition*
-lspconfig-root-detection	lspconfig.txt	/*lspconfig-root-detection*
-lspconfig-root-dir	lspconfig.txt	/*lspconfig-root-dir*
-lspconfig-scope	lspconfig.txt	/*lspconfig-scope*
-lspconfig-setup	lspconfig.txt	/*lspconfig-setup*
-lspconfig-single-file-support	lspconfig.txt	/*lspconfig-single-file-support*
-lspconfig-toc	lspconfig.txt	/*lspconfig-toc*
-lspconfig.txt	lspconfig.txt	/*lspconfig.txt*
-lspconfig-server-configurations	server_configurations.md	/# Configurations

scripts/README_template.md

@@ -1,4 +1,5 @@
 # Configurations
+<!-- *lspconfig-server-configurations* -->
 
 The following LSP configs are included. This documentation is autogenerated from the lua files. Follow a link to find documentation for
 that config. This file is accessible in neovim via `:help lspconfig-server-configurations`
@@ -6,3 +7,5 @@ that config. This file is accessible in neovim via `:help lspconfig-server-confi
 {{implemented_servers_list}}
 
 {{lsp_server_details}}
+
+vim:ft=markdown

scripts/docgen.lua

@@ -275,27 +275,7 @@ local function generate_readme(template_file, params)
   local writer = io.open('doc/server_configurations.md', 'w')
   writer:write(readme_data)
   writer:close()
-end
-
-local function generate_helptags()
-  -- Modify a help tag to point to server_configurations.md and append a modeline to it so it can be
-  -- displayed with the right filetype when using :help
-  vim.cmd [[
-  helptags ./doc
-  edit doc/tags
-  set noswapfile
-  set noreadonly
-  call append('$', "lspconfig-server-configurations	server_configurations.md	/# Configurations")
-  silent write
-  ]]
-  print 'Added doc/server_configurations.md to helptags'
-
-  vim.cmd [[
-  edit doc/server_configurations.md
-  call append('$', "vim:ft=markdown")
-  silent write
-  ]]
-  print 'Added modeline to doc/server_configurations.md'
+  uv.fs_copyfile('doc/server_configurations.md', 'doc/server_configurations.txt')
 end
 
 require_all_configs()
@@ -303,4 +283,3 @@ generate_readme('scripts/README_template.md', {
   implemented_servers_list = make_implemented_servers_list(),
   lsp_server_details = make_lsp_sections(),
 })
-generate_helptags()