Use a template for README.md (#28)

2 files changed, 195 insertions, 19 deletions

diff --git a/scripts/README_template.md b/scripts/README_template.md
new file mode 100644
index 00000000..049101bd
--- /dev/null
+++ b/scripts/README_template.md
@@ -0,0 +1,174 @@
+# nvim-lsp
+
+WIP Common configurations for Language Servers.
+
+This repository aims to be a central location to store configurations for
+Language Servers which leverage Neovim's built-in LSP client `vim.lsp` as the
+client backbone. The `vim.lsp` implementation is made to be customizable and
+greatly extensible, but most users just want to get up and going. This
+plugin/library is for those people, although it still lets you customize
+things as much as you want in addition to the defaults that this provides.
+
+**NOTE**: Requires current Neovim master as of 2019-11-13
+
+**CONTRIBUTIONS ARE WELCOME!**
+
+There's a lot of language servers in the world, and not enough time.  See
+[`lua/nvim_lsp/*.lua`](https://github.com/neovim/nvim-lsp/blob/master/lua/nvim_lsp/)
+for examples and ask us questions in the [Neovim
+Gitter](https://gitter.im/neovim/neovim) to help us complete configurations for
+*all the LSPs!* Read `CONTRIBUTING.md` for some instructions. NOTE: don't
+modify `README.md`; it is auto-generated.
+
+If you don't know where to start, you can pick one that's not in progress or
+implemented from [this excellent list compiled by the coc.nvim
+contributors](https://github.com/neoclide/coc.nvim/wiki/Language-servers) or
+[this other excellent list from the emacs lsp-mode
+contributors](https://github.com/emacs-lsp/lsp-mode#supported-languages)
+and create a new file under `lua/nvim_lsp/SERVER_NAME.lua`. We recommend
+looking at `lua/nvim_lsp/texlab.lua` for the most extensive example, but all of
+them are good references.
+
+## Progress
+
+Implemented language servers:
+{{implemented_servers_list}}
+
+Planned servers to implement (by me, but contributions welcome anyway):
+- [ccls](https://github.com/MaskRay/ccls)
+- [lua-language-server](https://github.com/sumneko/lua-language-server)
+- [rust-analyzer](https://github.com/rust-analyzer/rust-analyzer)
+
+In progress:
+- ...
+
+## Install
+
+`Plug 'neovim/nvim-lsp'`
+
+## Usage
+
+Servers configurations can be set up with a "setup function." These are
+functions to set up servers more easily with some server specific defaults and
+more server specific things like commands or different diagnostics.
+
+The "setup functions" are `call nvim_lsp#setup({name}, {config})` from vim and
+`nvim_lsp[name].setup(config)` from Lua.
+
+Servers may define extra functions on the `nvim_lsp.SERVER` table, e.g.
+`nvim_lsp.texlab.buf_build({bufnr})`.
+
+### Auto Installation
+
+Many servers can be automatically installed with the `:LspInstall`
+command. Detailed installation info can be found
+with the `:LspInstallInfo` command, which optionally accepts a specific server name.
+
+For example:
+```vim
+LspInstall elmls
+silent LspInstall elmls " useful if you want to autoinstall in init.vim
+LspInstallInfo
+LspInstallInfo elmls
+```
+
+### Example
+
+From vim:
+```vim
+call nvim_lsp#setup("texlab", {})
+```
+
+From Lua:
+```lua
+require 'nvim_lsp'.texlab.setup {
+  name = "texlab_fancy";
+  log_level = vim.lsp.protocol.MessageType.Log;
+  settings = {
+    latex = {
+      build = {
+        onSave = true;
+      }
+    }
+  }
+}
+
+local nvim_lsp = require 'nvim_lsp'
+
+-- Customize how to find the root_dir
+nvim_lsp.gopls.setup {
+  root_dir = nvim_lsp.util.root_pattern(".git");
+}
+
+-- Build the current buffer.
+require 'nvim_lsp'.texlab.buf_build(0)
+```
+
+### Setup function details
+
+The main setup signature will be:
+
+```
+nvim_lsp.SERVER.setup({config})
+
+  {config} is the same as |vim.lsp.start_client()|, but with some
+  additions and changes:
+
+  {root_dir}
+    May be required (depending on the server).
+    `function(filename, bufnr)` which is called on new candidate buffers to
+    attach to and returns either a root_dir or nil.
+
+    If a root_dir is returned, then this file will also be attached. You
+    can optionally use {filetype} to help pre-filter by filetype.
+
+    If a root_dir is returned which is unique from any previously returned
+    root_dir, a new server will be spawned with that root_dir.
+
+    If nil is returned, the buffer is skipped.
+
+    See |nvim_lsp.util.search_ancestors()| and the functions which use it:
+    - |nvim_lsp.util.root_pattern(patterns...)| finds an ancestor which
+    - contains one of the files in `patterns...`. This is equivalent
+    to coc.nvim's "rootPatterns"
+    - More specific utilities:
+      - |nvim_lsp.util.find_git_root()|
+      - |nvim_lsp.util.find_node_modules_root()|
+      - |nvim_lsp.util.find_package_json_root()|
+
+  {name}
+    Defaults to the server's name.
+
+  {filetypes}
+    A set of filetypes to filter for consideration by {root_dir}.
+    Can be left empty.
+    A server may specify a default value.
+
+  {log_level}
+    controls the level of logs to show from build processes and other
+    window/logMessage events. By default it is set to
+    vim.lsp.protocol.MessageType.Warning instead of
+    vim.lsp.protocol.MessageType.Log.
+
+  {settings}
+    This is a table, and the keys are case sensitive. This is for the
+    window/configuration event responses.
+    Example: `settings = { keyName = { subKey = 1 } }`
+
+  {on_attach}
+    `function(client)` will be executed with the current buffer as the
+    one the {client} is being attaching to. This is different from
+    |vim.lsp.start_client()|'s on_attach parameter, which passes the {bufnr} as
+    the second parameter instead. This is useful for running buffer local
+    commands.
+
+  {on_new_config}
+    `function(new_config)` will be executed after a new configuration has been
+    created as a result of {root_dir} returning a unique value. You can use this
+    as an opportunity to further modify the new_config or use it before it is
+    sent to |vim.lsp.start_client()|.
+```
+
+# LSP Implementations
+
+{{lsp_server_details}}
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index e33e88d0..a430e70b 100644
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -53,7 +53,7 @@ local skeleton_keys = vim.tbl_keys(skeleton)
 table.sort(skeleton_keys)
 
 local function make_lsp_sections()
-  return map_list(skeleton_keys, function(k)
+  local sections = map_list(skeleton_keys, function(k)
     local v = skeleton[k]
     local tconf = v.template_config
 
@@ -123,30 +123,32 @@ nvim_lsp#setup("{{template_name}}", {config})
 ```
 ]], params)
   end)
+  return table.concat(sections, '\n')
 end
 
-local function make_readme_preamble()
-  local data = io.open("README_preamble.md"):read("*a")
-  local implemented_server_marker = "Implemented language servers:"
-  return data:gsub(implemented_server_marker, function()
-    local lines = vim.tbl_flatten {
-      implemented_server_marker;
-      map_list(skeleton_keys, function(k)
-        return template("- [{{server}}](https://github.com/neovim/nvim-lsp#{{server}})", {server=k})
-      end)
-    }
-    return table.concat(lines, '\n')
+local function make_implemented_servers_list()
+  local parts = map_list(skeleton_keys, function(k)
+    return template("- [{{server}}](https://github.com/neovim/nvim-lsp#{{server}})", {server=k})
   end)
+  return table.concat(parts, '\n')
 end
 
-local writer = io.open("README.md", "w")
+local function generate_readme(params)
+  vim.validate {
+    lsp_server_details = {params.lsp_server_details, 's'};
+    implemented_servers_list = {params.implemented_servers_list, 's'};
+  }
+  local input_template = io.open("scripts/README_template.md"):read("*a")
+  local readme_data = template(input_template, params)
 
-local parts = vim.tbl_flatten {
-  make_readme_preamble();
-  make_lsp_sections();
-}
+  local writer = io.open("README.md", "w")
+  writer:write(readme_data)
+  writer:close()
+end
 
-writer:write(table.concat(parts, '\n'))
-writer:close()
+generate_readme {
+  implemented_servers_list = make_implemented_servers_list();
+  lsp_server_details = make_lsp_sections();
+}
 
 -- vim:et ts=2 sw=2