Improve documentation and docgen command.

Also improve the recommended command for running docgen.

4 files changed, 20 insertions, 16 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 407eba7b..efa8af67 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -11,8 +11,10 @@ from `nvim` to run.
 It **must** be run from the .git/project root. This could be modified to try to
 find the .git root with one of our `util.*` functions potentially.
 
-So you can either run nvim with cwd at the project root, or run `nvim +"luafile
-scripts/docgen.lua" +q` from the project root.
+You can run
+`nvim -u NONE +'set rtp+=$PWD' +"luafile scripts/docgen.lua" +q`
+from the project root. This ensures that it doesn't pick up another
+copy of `nvim_lsp` on your system.
 
 This generates a suffix for README.md
 
diff --git a/README.md b/README.md
index a7446a29..589129ea 100644
--- a/README.md
+++ b/README.md
@@ -26,17 +26,16 @@ 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`.
-- For a simple server which should only ever have one instance for the entire
-neovim lifetime, I recommend copying `lua/nvim_lsp/texlab.lua`.
-- For servers which should have a different instance for each project root, I
-recommend copying `lua/nvim_lsp/gopls.lua`.
+and create a new file under `lua/nvim_lsp/SERVER_NAME.lua`. I recommend looking
+at `lua/nvim_lsp/texlab.lua` for the most extensive example, but all of them
+are good references. Also read `CONTRIBUTING.md`.
 
 ## Progress
 
 Implemented:
 - [clangd](https://github.com/neovim/nvim-lsp#clangd)
 - [gopls](https://github.com/neovim/nvim-lsp#gopls) (has some errors)
+- [pyls](https://github.com/neovim/nvim-lsp#pyls)
 - [texlab](https://github.com/neovim/nvim-lsp#texlab)
 
 Planned servers to implement (by me, but contributions welcome anyway):
@@ -55,9 +54,10 @@ In progress:
 
 From vim:
 ```vim
-call nvim_lsp#setup("texlab", {})
+call nvim_lsp#setup("clangd", {})
 call nvim_lsp#setup("gopls", {})
 call nvim_lsp#setup("pyls", {})
+call nvim_lsp#setup("texlab", {})
 ```
 
 From Lua:
@@ -184,8 +184,7 @@ https://github.com/palantir/python-language-server
 python-language-server, a language server for Python
 
 the following settings (with default options) are supported:
-
-```
+```lua
 settings = {
   pyls = {
     enable = true;
diff --git a/README_preamble.md b/README_preamble.md
index 65bf5235..2b8eb6c4 100644
--- a/README_preamble.md
+++ b/README_preamble.md
@@ -26,17 +26,16 @@ 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`.
-- For a simple server which should only ever have one instance for the entire
-neovim lifetime, I recommend copying `lua/nvim_lsp/texlab.lua`.
-- For servers which should have a different instance for each project root, I
-recommend copying `lua/nvim_lsp/gopls.lua`.
+and create a new file under `lua/nvim_lsp/SERVER_NAME.lua`. I recommend looking
+at `lua/nvim_lsp/texlab.lua` for the most extensive example, but all of them
+are good references. Also read `CONTRIBUTING.md`.
 
 ## Progress
 
 Implemented:
 - [clangd](https://github.com/neovim/nvim-lsp#clangd)
 - [gopls](https://github.com/neovim/nvim-lsp#gopls) (has some errors)
+- [pyls](https://github.com/neovim/nvim-lsp#pyls)
 - [texlab](https://github.com/neovim/nvim-lsp#texlab)
 
 Planned servers to implement (by me, but contributions welcome anyway):
@@ -55,9 +54,10 @@ In progress:
 
 From vim:
 ```vim
-call nvim_lsp#setup("texlab", {})
+call nvim_lsp#setup("clangd", {})
 call nvim_lsp#setup("gopls", {})
 call nvim_lsp#setup("pyls", {})
+call nvim_lsp#setup("texlab", {})
 ```
 
 From Lua:
diff --git a/scripts/docgen.lua b/scripts/docgen.lua
index a2583a36..3b02949e 100644
--- a/scripts/docgen.lua
+++ b/scripts/docgen.lua
@@ -69,6 +69,9 @@ for k, v in pairs(skeleton) do
     for _, dk in ipairs(keys) do
       local dv = tconf.default_config[dk]
       local description = tconf.docs and tconf.docs.default_config and tconf.docs.default_config[dk]
+      if description and type(description) ~= 'string' then
+        description = inspect(description)
+      end
       table.insert(lines, indent(2, string.format("%s = %s", dk, description or inspect(dv))))
     end
     params.default_config = indent(0, table.concat(lines, '\n'))