docs: updated docs

folke · Apr 22, 2021 · 232c539 · 232c539
1 parent 160fa6c
commit 232c539
Show file tree

Hide file tree

Showing 4 changed files with 196 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,166 @@
-# lsp-trouble.nvim
 
-![image](https://user-images.githubusercontent.com/292349/115628665-d61df580-a2b5-11eb-8a8f-81b365b147d9.png)
+# 🚦 LSP Trouble
+
+A pretty diagnostics list to help your solve all the trouble your code is causing.
+
+## ✨ Features
+
+* pretty list of LSP Diagnostics
+* automatically updates on new diagnostics
+* toggle mode between **workspace** or **document**
+* **interactive preview** in your last accessed window
+* *cancel* preview or *jump* to the location
+* configurable actions, signs, highlights,...
+
+## ⚡️ Requirements
+
+* Neovim >= 0.5.0
+* Properly configured Neovim LSP client
+* [nvim-web-devicons](https://github.com/kyazdani42/nvim-web-devicons) is optional to enable file icons
+* a theme with properly configured highlight groups for Neovim LSP Diagnostics
+* a [patched font](https://www.nerdfonts.com/) for the default severity and fold icons
+
+## 📦 Installation
+
+Install the plugin with your preferred package manager:
+
+### [vim-plug](https://github.com/junegunn/vim-plug)
+
+```vim
+Plug 'kyazdani42/nvim-web-devicons'
+Plug 'folke/lsp-trouble.nvim'
+
+lua << EOF
+  require("trouble").setup {
+    -- your configuration comes here
+    -- or leave it empty to use the default settings
+    -- refer to the configuration section below
+  }
+EOF
+```
+
+### [packer](https://github.com/wbthomason/packer.nvim)
+
+```lua
+use {
+  "folke/lsp-trouble.nvim",
+  requires = "kyazdani42/nvim-web-devicons",
+  config = function()
+    require("trouble").setup {
+      -- your configuration comes here
+      -- or leave it empty to use the default settings
+      -- refer to the configuration section below
+    }
+  end
+}
+```
+
+## ⚙️ Configuration
+
+### Setup
+
+Trouble comes with the following defaults:
+
+```lua
+{
+    height = 10, -- height of the trouble list
+    icons = true, -- use dev-icons for filenames
+    mode = "workspace", -- "workspace" or "document"
+    fold_open = "", -- icon used for open folds
+    fold_closed = "", -- icon used for closed folds
+    action_keys = { -- key mappings for actions in the trouble list
+        close = "q", -- close the list
+        refresh = "r", -- manually refresh
+        jump = "<cr>", -- jump to the diagnostic or open / close folds
+        toggle_mode = "m", -- toggle between "workspace" and "document" mode
+        close_folds = "zM", -- close all folds
+        cancel = "<esc>", -- cancel the preview and get back to your last window / buffer / cursor
+        open_folds = "zR", -- open all folds
+        previous = "k", -- preview item
+        next = "j" -- next item
+    },
+    indent_lines = true, -- add an indent guide below the fold icons
+    auto_open = false, -- automatically open the list when you have diagnostics
+    auto_close = false, -- automatically close the list when you have no diagnostics
+    signs = {
+        -- icons / text used for a diagnostic
+        error = "",
+        warning = "",
+        hint = "",
+        information = ""
+    },
+    use_lsp_diagnostic_signs = false -- enabling this will use the signs defined in your lsp client
+}
+```
+
+> 💡 if you don't want to use icons or a patched font, you can use the settings below
+
+```lua
+-- settings without a patched font or icons
+{
+    fold_open = "v", -- icon used for open folds
+    fold_closed = ">", -- icon used for closed folds
+    indent_lines = false, -- add an indent guide below the fold icons
+    signs = {
+        -- icons / text used for a diagnostic
+        error = "error",
+        warning = "warn",
+        hint = "hint",
+        information = "info"
+    },
+    use_lsp_diagnostic_signs = false -- enabling this will use the signs defined in your lsp client
+}
+```
+
+## 🚀 Usage
+
+### Commands
+
+Trouble comes with the following commands:
+
+* **LspTroubleOpen**: open the list
+* **LspTroubleClose**: close the list
+* **LspTroubleToggle**: toggle the list
+* **LspTroubleRefresh**: manually refresh
+
+Example keybinding of `<leader>xx` that toggles the trouble list:
+
+```vim
+nnoremap <leader>xx <cmd>LspTroubleToggle<cr>
+```
+
+```lua
+-- bind <leader>xx to open LSP Trouble
+vim.api.nvim_set_keymap("n", "<leader>xx", "<cmd>LspTroubleToggle<cr>",
+  {silent = true, noremap = true}
+)
+```
+
+## 🎨 Colors
+
+The table below shows all the highlight groups defined for LSP Trouble with their default link.
+
+| Highlight Group             | Defaults to                      |
+| --------------------------- | -------------------------------- |
+| *LspTroubleCount*           | TabLineSel                       |
+| *LspTroubleError*           | LspDiagnosticsDefaultError       |
+| *LspTroubleNormal*          | Normal                           |
+| *LspTroubleTextInformation* | LspTroubleText                   |
+| *LspTroubleSignWarning*     | LspDiagnosticsSignWarning        |
+| *LspTroubleLocation*        | LineNr                           |
+| *LspTroubleWarning*         | LspDiagnosticsDefaultWarning     |
+| *LspTroublePreview*         | Search                           |
+| *LspTroubleTextError*       | LspTroubleText                   |
+| *LspTroubleSignInformation* | LspDiagnosticsSignInformation    |
+| *LspTroubleIndent*          | LineNr                           |
+| *LspTroubleSource*          | Comment                          |
+| *LspTroubleSignHint*        | LspDiagnosticsSignHint           |
+| *LspTroubleFoldIcon*        | CursorLineNr                     |
+| *LspTroubleTextWarning*     | LspTroubleText                   |
+| *LspTroubleCode*            | Comment                          |
+| *LspTroubleInformation*     | LspDiagnosticsDefaultInformation |
+| *LspTroubleSignError*       | LspDiagnosticsSignError          |
+| *LspTroubleFile*            | Directory                        |
+| *LspTroubleHint*            | LspDiagnosticsDefaultHint        |
+| *LspTroubleTextHint*        | LspTroubleText                   |
+| *LspTroubleText*            | Normal                           |
diff --git a/lua/trouble/colors.lua b/lua/trouble/colors.lua
@@ -25,6 +25,10 @@ local links = {
     Indent = "LineNr"
 }
 
+-- for key, value in pairs(links) do
+--     print("| **LspTrouble" .. key .. "* | " .. value .. " |")
+-- end
+
 function M.setup()
     for k, v in pairs(links) do
         vim.api.nvim_command('hi def link LspTrouble' .. k .. ' ' .. v)

diff --git a/lua/trouble/config.lua b/lua/trouble/config.lua
@@ -4,28 +4,33 @@ M.namespace = vim.api.nvim_create_namespace('LspTrouble')
 
 ---@class Options
 local defaults = {
-    height = 10,
-    icons = true,
-    mode = "document", -- "workspace" or "document"
-    fold_open = "",
-    fold_closed = "",
-    actions = {
-        ["<cr>"] = "jump",
-        ["<tab>"] = "jump",
-        ["<esc>"] = "cancel",
-        q = "close",
-        r = "refresh",
-        zR = "open_folds",
-        zM = "close_folds",
-        j = "next",
-        k = "previous",
-        m = "toggle_mode"
+    height = 10, -- height of the trouble list
+    icons = true, -- use devicons for filenames
+    mode = "workspace", -- "workspace" or "document"
+    fold_open = "", -- icon used for open folds
+    fold_closed = "", -- icon used for closed folds
+    action_keys = { -- key mappings for actions in the trouble list
+        close = "q", -- close the list
+        refresh = "r", -- manually refresh
+        jump = "<cr>", -- jump to the diagnostic or open / close folds
+        toggle_mode = "m", -- toggle between "workspace" and "document" mode
+        close_folds = "zM", -- close all folds
+        cancel = "<esc>", -- cancel the preview and get back to your last window / buffer / cursor
+        open_folds = "zR", -- open all folds
+        previous = "k", -- preview item
+        next = "j" -- next item
     },
-    indent_lines = false,
-    auto_open = false,
-    auto_close = true,
-    signs = {error = "", warning = "", hint = "", information = ""},
-    use_lsp_diagnostic_signs = false
+    indent_lines = true, -- add an indent guide below the fold icons
+    auto_open = false, -- automatically open the list when you have diagnostics
+    auto_close = false, -- automatically close the list when you have no diagnostics
+    signs = {
+        -- icons / text used for a diagnostic
+        error = "",
+        warning = "",
+        hint = "",
+        information = ""
+    },
+    use_lsp_diagnostic_signs = false -- enabling this will use the signs defined in your lsp client
 }
 
 ---@type Options

diff --git a/lua/trouble/view.lua b/lua/trouble/view.lua
@@ -130,7 +130,7 @@ function View:setup(opts)
     self:set_option("foldenable", false, true)
     self:set_option("winhighlight", "Normal:LspTroubleNormal", true)
 
-    for key, action in pairs(config.options.actions) do
+    for action, key in pairs(config.options.action_keys) do
         vim.api.nvim_buf_set_keymap(self.buf, "n", key,
                                     [[<cmd>lua require("trouble").action("]] ..
                                         action .. [[")<cr>]],