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.

8 files changed, 8 insertions, 46 deletions

diff --git a/.github/workflows/close-config-changes.yml b/.github/workflows/close-config-changes.yml
index 8ab231d8..b45a755e 100644
--- a/.github/workflows/close-config-changes.yml
+++ b/.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
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
index 7a6cfe13..e2876384 100644
--- a/.github/workflows/codespell.yml
+++ b/.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
diff --git a/.github/workflows/docgen.yml b/.github/workflows/docgen.yml
index 2e410a20..a0fdeaa5 100644
--- a/.github/workflows/docgen.yml
+++ b/.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)
diff --git a/.gitignore b/.gitignore
index eef77983..a928eeda 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 .luacheckcache
 neovim
+doc/tags
diff --git a/doc/server_configurations.txt b/doc/server_configurations.txt
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/server_configurations.txt
diff --git a/doc/tags b/doc/tags
deleted file mode 100644
index d4137d7b..00000000
--- a/doc/tags
+++ /dev/null
@@ -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
diff --git a/scripts/README_template.md b/scripts/README_template.md
index c077b147..3a9baeaa 100644
--- a/scripts/README_template.md
+++ b/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
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index f72b984e..f39beb8f 100644
--- a/scripts/docgen.lua
+++ b/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()