CONTRIBUTING.md

Requirements

• Neovim :P
• docgen requires a unix system.
• luacheck for linting Lua code. (Install)

Generating docs

NOTE: Github Actions automatically generates the docs, so only modify README_template.md or the docs object on the server config! DO NOT MODIFY README.md DIRECTLY

To preview the generated README.md locally, source scripts/docgen.lua from nvim (e.g. with :luafile):

nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'

It must be run from the .git/project root. (TODO: try to find the .git root with one of our util.* functions?)

skeleton

skeleton has a __newindex metamethod which validates and creates an object containing setup(), which can then be retrieved and modified.

In vim.validate parlance, this is the "spec":

skeleton.SERVER_NAME = {
  default_config = {'t'};
  on_new_config = {'f', true};
  on_attach = {'f', true};
  commands = {'t', true};
  docs = {'t', true};
}
docs = {
  description = {'s', true};
  default_config = {'t', true};
}

• Keys of the docs.default_config table match those of skeleton.SERVER_NAME.default_config, and can be used to specify custom 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.

Example:

  commands = {
    TexlabBuild = {
      function()
        buf_build(0)
      end;
      "-range";
      description = "Build the current buffer";
    };
  };

After you create skeleton.SERVER_NAME, you may add arbitrary language-specific functions to it if necessary.

Example:

skeleton.texlab.buf_build = buf_build

Finally, add a require 'nvim_lsp/SERVER_NAME' line to lua/nvim_lsp.lua.

Auto-installation

Configs may optionally provide install() and install_info() functions. This will be recognized by :LspInstall and :LspInstallInfo.

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 with npm. See elmls.lua, tsserver.lua, or bashls.lua for examples.