docs: documentation overhaul (#1384)

* remove automated generation of vimdoc + ci
* unify ADVANCED_README.md and vimdoc
* rename CONFIGS.md to server_configurations.md, move into doc folder
* move CONTRIBUTING.md to .github folder

2 files changed, 88 insertions, 41 deletions

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 00000000..2ac4f6c8
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,88 @@
+## Requirements
+
+- [Neovim](https://neovim.io/) 0.5 or later
+- Lint task requires [luacheck](https://github.com/luarocks/luacheck#installation) and [stylua](https://github.com/JohnnyMorganz/StyLua). If using nix, you can use `nix develop` to install these to a local nix shell.
+- Documentation is generated by `scripts/docgen.lua`.
+  - Only works on linux and macOS
+
+## Scope of lspconfig
+
+The point of lspconfig is to provide the minimal configuration necessary for a server to act in compliance with the language server protocol. In general, if a server requires custom client-side commands or  off-spec handlers, then the server configuration should be added *without* those in lspconfig and receive a dedicated plugin such as nvim-jdtls, nvim-metals, etc.
+
+## Adding a server to lspconfig
+
+The general form of adding a new language server is to start with a minimal skeleton. This includes populated the `config` table with a `default_config` and `docs` table.
+
+`default_config` should include, at minimum the following:
+* `cmd`: a list which includes the executable name as the first entry, with arguments constituting subsequent list elements (`--stdio` is common)
+* `filetypes`: a list for filetypes a 
+* `root_dir`: a function (or function handle) which returns the root of the project used to determine if lspconfig should launch a new language server, or attach a previously launched server when you open a new buffer matching the filetype of the server. Note, lspconfig does not offer a dedicated single file mode (this is not codified in the spec). Do not add `vim.fn.cwd` or `util.path.dirname` in `root_dir`. A future version of lspconfig will provide emulation of a single file mode until this is formally codified in the specification. A good fallback is `util.find_git_ancestor`, see other configurations for examples.
+
+Additionally, the following options are often added:
+
+* `init_options`: a table sent during initialization, corresponding to initializationOptions sent in [initializeParams](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#initializeParams) as part of the first request sent from client to server during startup.
+* `settings`: a table sent during [`workspace/didChangeConfiguration`](https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#didChangeConfigurationParams) shortly after server initialization. This is an undocumented convention for most language servers. There is often some duplication with initOptions.
+
+A minimal example for adding a new language server is shown below for `pyright`, a python language server included in lspconfig:
+
+```lua
+-- Only `configs` must be required, util is optional if you are using the root resolver functions, which is usually the case.
+local configs = require 'lspconfig/configs'
+local util = require 'lspconfig/util'
+
+-- Having server name defined here is the convention, this is often times also the first entry in the `cmd` table.
+local server_name = 'pyright'
+
+configs[server_name] = {
+  default_config = {
+    -- This should be executable on the command line, arguments (such as `--stdio`) are additional entries in the list.
+    cmd = { 'pyright-langserver' },
+    -- These are the filetypes that the server will either attach or start in response to opening. The user must have a filetype plugin matching the filetype, either via the built-in runtime files or installed via plugin.
+    filetypes = { 'python' },
+    -- The root directory that lspconfig uses to determine if it should start a new language server, or attach the current buffer to a previously running language server.
+    root_dir = util.find_git_ancestor
+    end,
+  },
+  docs = {
+    -- extremely important: the package.json that contains language server settings, not the package.json that contains javascript dependencies for the project, or the package.json that contains vscode specific settings
+    package_json = 'https://raw.githubusercontent.com/microsoft/pyright/master/packages/vscode-pyright/package.json',
+
+    -- The description should include at minimum the link to the github project, and ideally the steps to install the language server.
+    description = [[
+https://github.com/microsoft/pyright
+
+`pyright`, a static type checker and language server for python
+
+`pyright` can be installed via `npm`
+`npm install -g pyright`
+]],
+  },
+}
+```
+
+## Commit style
+
+lspconfig, like neovim core, follows the [conventional commit style](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) please submit your commits accordingly. Generally commits will be of the form:
+
+```
+feat: add lua-language-server support
+fix(lua-language-server): update root directory pattern
+docs: update README.md
+```
+
+with the commit body containing additional details.
+
+## Lint
+
+PRs are checked with Luacheck and stylua. Please run the linter locally before submitting a PR:
+
+    make lint
+
+## Generating docs
+
+Github Actions automatically generates `server_configurations.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config (the lua file). Do not modify `server_configurations.md` directly.
+
+To preview the generated `server_configurations.md` locally, run `scripts/docgen.lua` from
+`nvim` (from the project root):
+
+    nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
diff --git a/.github/workflows/docgen.yml b/.github/workflows/docgen.yml
index 0415ed53..a6c3bd55 100644
--- a/.github/workflows/docgen.yml
+++ b/.github/workflows/docgen.yml
@@ -30,44 +30,3 @@ jobs:
         git add CONFIG.md
         # Only commit and push if we have changes
         git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push)
-  vimdocgen:
-    needs: docgen
-    runs-on: [ubuntu-latest]
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v2
-      - uses: rhysd/action-setup-vim@v1
-        with:
-          neovim: true
-          version: nightly
-      - name: Install plugins
-        run: |
-          mkdir -p ~/.local/share/nvim/site/pack/vendor/start
-          git clone --depth 1 https://github.com/mjlbach/babelfish.nvim ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim
-          git clone --depth 1 https://github.com/nvim-treesitter/nvim-treesitter ~/.local/share/nvim/site/pack/vendor/start/nvim-treesitter
-          ln -s $(pwd) ~/.local/share/nvim/site/pack/vendor/start
-
-      - name: Build parser
-        run: |
-          export PACKPATH=$HOME/.local/share/nvim/site
-          nvim -u ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim/scripts/init.lua --headless -c 'TSInstallSync markdown' -c 'qa'
-      - name: Generating docs
-        run: |
-          export PATH="${PWD}/build/:${PATH}"
-          export PACKPATH=$HOME/.local/share/nvim/site
-          nvim -u ~/.local/share/nvim/site/pack/vendor/start/babelfish.nvim/scripts/init.lua --headless -c 'luafile ./scripts/vimdocgen.lua' -c 'qa'
-      - name: Commit changes
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          COMMIT_MSG: |
-            docs: update README.md
-            skip-checks: true
-        run: |
-          git config user.email "actions@github"
-          git config user.name "Github Actions"
-          git remote set-url origin https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
-          git pull
-          git add doc/lspconfig.txt
-          # Only commit and push if we have changes
-          git diff --quiet && git diff --staged --quiet || (git commit -m "${COMMIT_MSG}"; git push origin HEAD:${GITHUB_REF})