diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 4 | ||||
| -rw-r--r-- | doc/lspconfig.txt | 40 | ||||
| -rw-r--r-- | doc/tags | 21 | ||||
| -rw-r--r-- | scripts/README_template.md | 2 | ||||
| -rw-r--r-- | scripts/docgen.lua | 22 |
6 files changed, 65 insertions, 25 deletions
@@ -1,3 +1,2 @@ .luacheckcache neovim -doc/tags @@ -41,7 +41,7 @@ These features are not implemented in this repo, but in Neovim core. See `:help npm i -g pyright ``` -2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [server_configurations.md](doc/server_configurations.md) +2. Add the language server setup to your init.vim. The server name must match those found in the table of contents in [server_configurations.md](doc/server_configurations.md). This list is also accessible via `:help lspconfig-server-configurations`. ```lua lua << EOF @@ -82,7 +82,7 @@ require'lspconfig'.rust_analyzer.setup{} EOF ``` -For a full list of servers, see [server_configurations.md](doc/server_configurations.md). This document contains installation instructions and additional, optional customization suggestions for each language server. For some servers that are not on your system path (jdtls, elixirls) you will be required to manually add `cmd` as an entry in the table passed to setup. Most language servers can be installed in less than a minute. +For a full list of servers, see [server_configurations.md](doc/server_configurations.md) or `:help lspconfig-server-configurations`. This document contains installation instructions and additional, optional, customization suggestions for each language server. For some servers that are not on your system path (e.g., `jdtls`, `elixirls`), you will be required to manually add `cmd` as an entry in the table passed to `setup`. Most language servers can be installed in less than a minute. ## Keybindings and completion diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt index 71e34da9..82be54d5 100644 --- a/doc/lspconfig.txt +++ b/doc/lspconfig.txt @@ -9,7 +9,6 @@ TABLE OF CONTENTS *lspconfig-toc* 5. Global defaults (|lspconfig-global-defaults|) 6. Server configurations (|lspconfig-configurations|) 6a. Adding servers (|lspconfig-adding-servers|) - 6b. Index (|lspconfig-index|) 7. Root directories (|lspconfig-root-detection|) 7a. Advanced detection (|lspconfig-root-advanced|) 7b. Single file support (|lspconfig-single-file-support|) @@ -39,8 +38,8 @@ primary functionalities: `lspconfig` is not required to use the built-in client, it is only one front-end interface for when a language server specific plugin is not available. -See |lspconfig-index| for the reference to the complete list of language -servers. +See |lspconfig-server-configurations| by typing `K` over it for the complete +list of language servers configurations. ============================================================================== LSP OVERVIEW *lspconfig-lsp* @@ -73,11 +72,14 @@ QUICKSTART *lspconfig-quickstart* > require'lspconfig'.clangd.setup{} < -- create a new project, ensure it contains a root marker which matches the - server requirements specified in `server_configurations.md`. +- create a new project, ensure that it contains a root marker which matches the + server requirements specified in |lspconfig-server-configurations|. - open a file within that project, such as `main.c`. +- If you need more information about a server configuration, read the corresponding + entry in |lspconfig-server-configurations|. + ============================================================================== THE SETUP METAMETHOD *lspconfig-setup* @@ -90,9 +92,9 @@ Using the default configuration for a server is simple: > require'lspconfig'.clangd.setup{} < -The available server names are listed in `server_configurations.md` and match -the server name in `config.SERVER_NAME` defined in each configuration's source -file. +The available server names are listed in |lspconfig-server-configurations| and +match the server name in `config.SERVER_NAME` defined in each configuration's +source file. The purpose of `setup{}` is to wrap the call to Nvim's built-in `vim.lsp.start_client()` with an autocommand that automatically launch a @@ -218,7 +220,7 @@ passed overrides to `setup {}` are: The script that automatically generates `server_configurations.md` converts the `package.json` referenced in a server configuration source file - into a list of optional settings listed in `server_configurations.md`. + into a list of optional settings listed in |lspconfig-server-configurations|. As an example, to set the following settings found in the pyright documentation: @@ -245,7 +247,7 @@ passed overrides to `setup {}` are: ============================================================================== -OVERRIDING GLOBAL DEFAULTS *lspconfig-global-defaults* +OVERRIDING GLOBAL DEFAULTS *lspconfig-global-defaults* The global defaults for all servers can be overridden by extending the `default_config` table. @@ -277,6 +279,9 @@ The global defaults for all servers can be overridden by extending the ============================================================================== SERVER CONFIGURATIONS *lspconfig-configurations* +See |lspconfig-server-configurations| by typing `K` over it for the complete +list of language servers configurations. + While the `setup {}` function is the primary interface to `lspconfig`, for servers for which there is not a configuration, it is necessary to define a configuration directly. This can be useful if there is an outstanding PR that @@ -362,13 +367,6 @@ The three steps for adding and enabling a new server configuration are: lspconfig.foo_lsp.setup{} < ============================================================================== -INDEX *lspconfig-index* - -The autogenerated documentation for all language servers is accessible in -`server_configurations.md`. Type `gf` on the filename from this document to jump -to the markdown file. - -============================================================================== ROOT DETECTION *lspconfig-root-detection* *lspconfig-root-dir* @@ -479,15 +477,15 @@ that require a client id can either leverage tab-completion or the info contained in `:LspInfo`: - `:LspStart <config_name>` launches the requested (configured) client, but only - if it successfully resolves a root directory. Defaults to all *configured* - servers matching the *current* *buffer's* filetype. + if it successfully resolves a root directory. Note: Defaults to all + configured servers matching the current buffer filetype. - `:LspStop <client_id>` stops the server with the given client id. Defaults to stopping all servers active on the current buffer. - `:LspRestart <client_id>` restarts the client with the given client id, and will attempt to reattach to all previously attached buffers. ============================================================================== -EXAMPLE KEYBINDINGS *lspconfig-keybindings* +EXAMPLE KEYBINDINGS *lspconfig-keybindings* `lspconfig`, and the core client, do not map any keybindings by default. The following is an example Lua block which demonstrates how to leverage @@ -572,7 +570,7 @@ The first step in debugging is to test with a minimal configuration (such as plugins or misconfiguration. Should that fail, identifying which component is the culprit is challenging. -The following are the *only* categories of bugs that pertain to `lspconfig`. +The following are the only categories of bugs that pertain to `lspconfig`. - The root directory inferred for your project is wrong, or it should be detected but is not due to a bug in the `lspconfig` path utilities. diff --git a/doc/tags b/doc/tags new file mode 100644 index 00000000..d4137d7b --- /dev/null +++ b/doc/tags @@ -0,0 +1,21 @@ +lspconfig lspconfig.txt /*lspconfig* +lspconfig-adding-servers lspconfig.txt /*lspconfig-adding-servers* +lspconfig-commands lspconfig.txt /*lspconfig-commands* +lspconfig-completion lspconfig.txt /*lspconfig-completion* +lspconfig-configurations lspconfig.txt /*lspconfig-configurations* +lspconfig-debugging lspconfig.txt /*lspconfig-debugging* +lspconfig-global-defaults lspconfig.txt /*lspconfig-global-defaults* +lspconfig-keybindings lspconfig.txt /*lspconfig-keybindings* +lspconfig-logging lspconfig.txt /*lspconfig-logging* +lspconfig-lsp lspconfig.txt /*lspconfig-lsp* +lspconfig-quickstart lspconfig.txt /*lspconfig-quickstart* +lspconfig-root-advanced lspconfig.txt /*lspconfig-root-advanced* +lspconfig-root-composition lspconfig.txt /*lspconfig-root-composition* +lspconfig-root-detection lspconfig.txt /*lspconfig-root-detection* +lspconfig-root-dir lspconfig.txt /*lspconfig-root-dir* +lspconfig-scope lspconfig.txt /*lspconfig-scope* +lspconfig-setup lspconfig.txt /*lspconfig-setup* +lspconfig-single-file-support lspconfig.txt /*lspconfig-single-file-support* +lspconfig-toc lspconfig.txt /*lspconfig-toc* +lspconfig.txt lspconfig.txt /*lspconfig.txt* +lspconfig-server-configurations server_configurations.md /# Configurations diff --git a/scripts/README_template.md b/scripts/README_template.md index becd1728..c077b147 100644 --- a/scripts/README_template.md +++ b/scripts/README_template.md @@ -1,7 +1,7 @@ # Configurations The following LSP configs are included. This documentation is autogenerated from the lua files. Follow a link to find documentation for -that config. +that config. This file is accessible in neovim via `:help lspconfig-server-configurations` {{implemented_servers_list}} diff --git a/scripts/docgen.lua b/scripts/docgen.lua index 7d0bf626..f72b984e 100644 --- a/scripts/docgen.lua +++ b/scripts/docgen.lua @@ -277,8 +277,30 @@ local function generate_readme(template_file, params) writer:close() end +local function generate_helptags() + -- Modify a help tag to point to server_configurations.md and append a modeline to it so it can be + -- displayed with the right filetype when using :help + vim.cmd [[ + helptags ./doc + edit doc/tags + set noswapfile + set noreadonly + call append('$', "lspconfig-server-configurations server_configurations.md /# Configurations") + silent write + ]] + print 'Added doc/server_configurations.md to helptags' + + vim.cmd [[ + edit doc/server_configurations.md + call append('$', "vim:ft=markdown") + silent write + ]] + print 'Added modeline to doc/server_configurations.md' +end + require_all_configs() generate_readme('scripts/README_template.md', { implemented_servers_list = make_implemented_servers_list(), lsp_server_details = make_lsp_sections(), }) +generate_helptags() |