2019-11-14 08:50:01 +00:00
|
|
|
# Requirements
|
|
|
|
|
|
|
|
- Neovim :P
|
2019-12-08 06:10:33 +00:00
|
|
|
- docgen requires a unix system.
|
2019-12-31 22:15:50 +00:00
|
|
|
- luacheck for linting Lua code. ([Install](https://github.com/mpeterv/luacheck#installation))
|
2019-11-14 08:50:01 +00:00
|
|
|
|
|
|
|
# Generating docs
|
|
|
|
|
2019-11-14 23:20:31 +00:00
|
|
|
> NOTE: Github Actions automatically generates the docs, so only modify
|
2019-12-08 06:10:33 +00:00
|
|
|
> `README_template.md` or the `docs` object on the server config!
|
|
|
|
> **DO NOT MODIFY `README.md` DIRECTLY**
|
2019-11-14 23:20:31 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
To preview the generated `README.md` locally, source `scripts/docgen.lua` from
|
|
|
|
`nvim` (e.g. with `:luafile`):
|
2019-11-14 23:20:31 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
|
2019-11-14 08:50:01 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
It **must** be run from the `.git`/project root. (TODO: try to find the `.git`
|
|
|
|
root with one of our `util.*` functions?)
|
2019-11-14 23:20:31 +00:00
|
|
|
|
2020-01-31 08:00:50 +00:00
|
|
|
# configs
|
2019-11-14 08:50:01 +00:00
|
|
|
|
2020-01-31 08:00:50 +00:00
|
|
|
configs has a `__newindex` metamethod which validates and creates
|
2019-11-14 08:50:01 +00:00
|
|
|
an object containing `setup()`, which can then be retrieved and modified.
|
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
In `vim.validate` parlance, this is the "spec":
|
2019-11-14 08:50:01 +00:00
|
|
|
|
|
|
|
```
|
2020-01-31 08:00:50 +00:00
|
|
|
configs.SERVER_NAME = {
|
2019-11-14 08:51:30 +00:00
|
|
|
default_config = {'t'};
|
|
|
|
on_new_config = {'f', true};
|
|
|
|
on_attach = {'f', true};
|
|
|
|
commands = {'t', true};
|
|
|
|
docs = {'t', true};
|
2019-11-14 08:50:01 +00:00
|
|
|
}
|
|
|
|
docs = {
|
|
|
|
description = {'s', true};
|
|
|
|
default_config = {'t', true};
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
- Keys of the `docs.default_config` table match those of
|
2020-01-31 08:00:50 +00:00
|
|
|
`configs.SERVER_NAME.default_config`, and can be used to specify custom
|
2019-12-08 06:10:33 +00:00
|
|
|
documentation. This is useful for functions, whose docs cannot be easily
|
|
|
|
auto-generated.
|
|
|
|
- The `commands` object is a table of `name:definition` key:value pairs, where
|
|
|
|
`definition` is a list whose first value is a function implementing the
|
|
|
|
command. The other table values are either array values which will be formed
|
|
|
|
into flags for the command or special keys like `description`.
|
2019-11-14 08:50:01 +00:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
```
|
|
|
|
commands = {
|
|
|
|
TexlabBuild = {
|
|
|
|
function()
|
|
|
|
buf_build(0)
|
|
|
|
end;
|
2019-11-14 08:51:30 +00:00
|
|
|
"-range";
|
2019-11-14 08:50:01 +00:00
|
|
|
description = "Build the current buffer";
|
|
|
|
};
|
|
|
|
};
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2020-01-31 08:00:50 +00:00
|
|
|
After you create `configs.SERVER_NAME`, you may add arbitrary
|
2019-12-08 06:10:33 +00:00
|
|
|
language-specific functions to it if necessary.
|
2019-11-14 08:50:01 +00:00
|
|
|
|
|
|
|
Example:
|
|
|
|
|
2020-01-31 08:00:50 +00:00
|
|
|
configs.texlab.buf_build = buf_build
|
2019-11-14 08:50:01 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
Finally, add a `require 'nvim_lsp/SERVER_NAME'` line to `lua/nvim_lsp.lua`.
|
2019-11-16 01:26:22 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
# Auto-installation
|
2019-11-16 01:26:22 +00:00
|
|
|
|
2019-12-08 06:10:33 +00:00
|
|
|
Configs may optionally provide `install()` and `install_info()` functions.
|
|
|
|
This will be recognized by `:LspInstall` and `:LspInstallInfo`.
|
2019-11-16 01:26:22 +00:00
|
|
|
|
|
|
|
`function install()` is the signature and it is expected that it will create
|
|
|
|
any data in `util.base_install_dir/{server_name}`.
|
|
|
|
|
|
|
|
`function install_info()` should return a table with at least `is_installed`
|
|
|
|
which indicates the current status of installation (if it is installed by us).
|
|
|
|
It can contain any other additional data that the user may find useful.
|
|
|
|
|
|
|
|
The helper function `util.npm_installer` can be used for lsps which are installed
|
2019-12-08 06:10:33 +00:00
|
|
|
with `npm`. See `elmls.lua`, `tsserver.lua`, or `bashls.lua` for examples.
|