From 7922f990aeefa6df09f4ff3d278f92910ae89157 Mon Sep 17 00:00:00 2001 From: hedyhli Date: Wed, 8 Nov 2023 05:57:25 +0000 Subject: [PATCH] Auto generate vim docs --- doc/symbols-outline.txt | 390 ++++++++++++++++++++++++---------------- 1 file changed, 240 insertions(+), 150 deletions(-) diff --git a/doc/symbols-outline.txt b/doc/symbols-outline.txt index aaffb4e..8ae2a89 100644 --- a/doc/symbols-outline.txt +++ b/doc/symbols-outline.txt @@ -19,6 +19,8 @@ Table of Contents *symbols-outline-table-of-contents* - Commands |symbols-outline-symbols-outline.nvim-commands| - Default keymaps |symbols-outline-symbols-outline.nvim-default-keymaps| - Highlights |symbols-outline-symbols-outline.nvim-highlights| + - Lua API |symbols-outline-symbols-outline.nvim-lua-api| + - Tips |symbols-outline-symbols-outline.nvim-tips| - Recipes |symbols-outline-symbols-outline.nvim-recipes| ============================================================================== @@ -84,10 +86,34 @@ FIXES *symbols-outline-fork-status-fixes* This section may be relevant to you if your existing config uses the mentioned features: +- **Config**: Configuration options have been significantly restructured to + provide better consistency and understandability. Please see the + |symbols-outline-default-config| for an example of the full list. + - Options that control the looks + and behaviour of outline window is now moved to `outline_window` table; + - Options that control the items that show up are now in `outline_items` + - Options for the preview window is in `preview_window`. + - Symbol icons are now in `symbols.icons`, symbol blacklists are in + `symbols.blacklist` + - Lsp blacklists are now in `providers.lsp.blacklist_clients`. + - Fold options are now in `symbol_folding` with `fold_markers` being + `symbol_folding.markers`, consistent to `guides.markers`. + The reasoning for the above is simple. When you see 'border' under + `preview_window` you can directly infer it controls the border for the preview + window. Previously, for example, when you see `winblend` or `wrap`: is it for + the outline window or the preview window? Furthermore, this change also aids + extensibility to the configuration, and avoids cluttering the root setup opts + namespace. + If you disagree with this decision, you are always free to switch back to the + original symbols-outline.nvim, or you could pin a commit in this fork if you + still want to use the features and fixes from here. - **Config**: `keymaps.focus_location` RENAMED to `keymaps.peek_location` to avoid confusion with focus window commands. - **Config**: Marker icons used for guides can now be customized. `show_guides` REMOVED in favor of `guides.enabled`. + You can set `guides = false` to disable guides altogether, or set `guides = + true` to enable it but use default configuration for the guides. Otherwise, + please use `guides.enabled` if your configuration for `guides` is a table. - **Behaviour**: Removed hover floating window from `toggle_preview`. - Instead, you can set `open_hover_on_preview=true` (true by default) so that the `hover_symbol` action can be triggered when `toggle_preview`is @@ -129,7 +155,8 @@ Features/Changes: - Cursorline option for the outline window. - Added function and command to show provider and outline window status, somewhat like `:LspInfo`. -- Move down/up by one line and peek_location immediately. +- Move down/up by one line and peek_location immediately, default bindings are + `` and `` just like Aerial. - Flash highlight when using goto/peek location. - Auto jump config option (see config `auto_goto`) (simrat39/symbols-outline.nvim#229, simrat39/symbols-outline.nvim#228). @@ -137,7 +164,8 @@ Features/Changes: - New restore location keymap option to go back to corresponding outline location synced with code (see config `restore_location`). -Screen recordings of some of the features is shown at the bottom of the readme. +Screen recordings of some of the features is shown at the +|symbols-outline-bottom-of-the-readme|. PRS *symbols-outline-fork-status-prs* @@ -239,11 +267,12 @@ Table of contents - |symbols-outline-setup| - |symbols-outline-configuration| - |symbols-outline-terminology| - - |symbols-outline-options| + - |symbols-outline-default-options| - |symbols-outline-commands| - - |symbols-outline-lua-api| - |symbols-outline-default-keymaps| - |symbols-outline-highlights| +- |symbols-outline-lua-api| +- |symbols-outline-tips| - |symbols-outline-recipes| @@ -255,19 +284,17 @@ PREREQUISITES *symbols-outline-symbols-outline.nvim-prerequisites* INSTALLATION *symbols-outline-symbols-outline.nvim-installation* -Use `hedyhli/symbols-outline.nvim` if you wish to use this fork. - Packer: >lua - use 'simrat39/symbols-outline.nvim' + use 'hedyhli/symbols-outline.nvim' < Lazy: >lua { - "simrat39/symbols-outline.nvim", + "hedyhli/symbols-outline.nvim", config = function() -- Example mapping to toggle outline vim.keymap.set("n", "tt", "SymbolsOutline", @@ -284,11 +311,11 @@ Lazy with lazy-loading: >lua { - "simrat39/symbols-outline.nvim", + "hedyhli/symbols-outline.nvim", cmd = { "SymbolsOutline", "SymbolsOutlineOpen" }, keys = { -- Example mapping to toggle outline - { "tt", "SymbolsOutline", desc = "Toggle outline window" }, + { "tt", "SymbolsOutline", desc = "Toggle outline" }, }, opts = { -- Your setup opts here @@ -314,9 +341,15 @@ Note that a call to `.setup()` is _required_ for this plugin to work CONFIGURATION *symbols-outline-symbols-outline.nvim-configuration* +The configuration structure has been heavily improved and refactored in this +plugin. For details and reasoning, see |symbols-outline-breaking-changes|. + TERMINOLOGY ~ +Check this list if you there’s any confusion with the terms used in the +configuration. + - **Provider**: Source of the items in the outline view. Could be LSP, CoC, etc. - **Node**: An item in the outline view - **Fold**: Collapse a collapsible node @@ -329,23 +362,56 @@ TERMINOLOGY ~ - **Focus**: Which window the cursor is in -OPTIONS ~ +DEFAULT OPTIONS ~ Pass a table to the setup call with your configuration options. Default values are shown: >lua - local opts = { - -- Where to open the split window: right/left - position = 'right', - -- Whether width is relative to existing windows - relative_width = true, - -- Percentage or integer of columns - width = 25, + { + outline_window = { + -- Where to open the split window: right/left + position = 'right', + -- Percentage or integer of columns + width = 25, + -- Whether width is relative to existing windows + relative_width = true, + + -- Behaviour changed in this fork: + -- Auto close the outline window if goto_location is triggered and not for + -- peek_location + auto_close = false, + -- Automatically go to location in code when navigating outline window. + -- Only in this fork + auto_goto = false, + + -- Vim options for the outline window + show_numbers = false, + show_relative_numbers = false, + show_cursorline = true, -- Only in this fork + + -- Whether to wrap long lines, or let them flow off the window + wrap = false, + -- Only in this fork: + -- Whether to focus on the outline window when it is opened. + -- Set to false to remain focus on your previous buffer when opening + -- symbols-outline. + focus_on_open = true, + }, + + outline_items = { + -- Whether to highlight the currently hovered symbol (high cpu usage) + highlight_hovered_item = true, + -- Show extra details with the symbols (lsp dependent) + show_symbol_details = true, + -- Only in this fork. + -- Show line numbers of each symbol next to them. + -- Why? See this comment: + -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563 + show_symbol_lineno = false, + }, - -- Whether to highlight the currently hovered symbol (high cpu usage) - highlight_hovered_item = true, -- Options for outline guides. -- Only in this fork guides = { @@ -357,54 +423,35 @@ Default values are shown: horizontal = '─', }, }, - -- Automatically open preview of code on hover - auto_preview = false, - -- Automatically open hover_symbol when opening toggle_preview (see keymaps). - -- If you disable this you can still open hover_symbol using your keymap - -- below. - -- Only in this fork - open_hover_on_preview = true, - -- Border option for floating preview window. - -- Options include: single/double/rounded/solid/shadow or an array of border - -- characters. - -- See :help nvim_open_win() and search for "border" option. - border = 'single', - -- Behaviour changed in this fork: - -- Auto close the outline window if goto_location is triggered and not for - -- peek_location - auto_close = false, - -- Automatically go to location in code when navigating outline window. - -- Only in this fork - auto_goto = false, - -- Vim options for the outline window - show_numbers = false, - show_relative_numbers = false, - show_cursorline = true, -- Only in this fork - -- Show extra details with the symbols (lsp dependent) - show_symbol_details = true, - -- Only in this fork. - -- Show line numbers of each symbol next to them. - -- Why? See this comment: - -- https://github.com/simrat39/symbols-outline.nvim/issues/212#issuecomment-1793503563 - show_symbol_lineno = false, - -- Highlight group for the preview background - preview_bg_highlight = 'Pmenu', - -- Depth past which nodes will be folded by default - autofold_depth = nil, - -- Automatically unfold hovered symbol - auto_unfold_hover = true, - fold_markers = { '', '' }, - -- Whether to wrap long lines, or let them flow off the window - wrap = false, + symbol_folding = { + -- Depth past which nodes will be folded by default + autofold_depth = nil, + -- Automatically unfold hovered symbol + auto_unfold_hover = true, + markers = { '', '' }, + }, - -- Only in this fork: - -- Whether to focus on the outline window when it is opened. - -- Set to false to remain focus on your previous buffer when opening - -- symbols-outline. - focus_on_open = true, - -- Pseudo-transparency of the preview window - winblend = 0 + preview_window = { + -- Automatically open preview of code location when navigating outline window + auto_preview = false, + -- Automatically open hover_symbol when opening preview (see keymaps for + -- hover_symbol). + -- If you disable this you can still open hover_symbol using your keymap + -- below. + -- Only in this fork + open_hover_on_preview = true, + -- Border option for floating preview window. + -- Options include: single/double/rounded/solid/shadow or an array of border + -- characters. + -- See :help nvim_open_win() and search for "border" option. + border = 'single', + border_hl = 'Pmenu', + -- Highlight group for the preview background + bg_hl = 'Pmenu', + -- Pseudo-transparency of the preview window + winblend = 0 + }, -- These keymaps can be a string or a table for multiple keys keymaps = { @@ -445,52 +492,58 @@ Default values are shown: up_and_goto = '', }, - -- Lsp clients to ignore - lsp_blacklist = {}, - -- Symbols to ignore. - -- Possible values: lua/symbols-outline/symbols.lua - symbol_blacklist = {}, + providers = { + lsp = { + -- Lsp client names to ignore + blacklist_clients = {}, + }, + }, symbols = { - -- Changed in this fork - File = { icon = "󰈔", hl = "@text.uri" }, - Module = { icon = "󰆧", hl = "@namespace" }, - Namespace = { icon = "󰅪", hl = "@namespace" }, - Package = { icon = "󰏗", hl = "@namespace" }, - Class = { icon = "𝓒", hl = "@type" }, - Method = { icon = "ƒ", hl = "@method" }, - Property = { icon = "", hl = "@method" }, - Field = { icon = "󰆨", hl = "@field" }, - Constructor = { icon = "", hl = "@constructor" }, - Enum = { icon = "ℰ", hl = "@type" }, - Interface = { icon = "󰜰", hl = "@type" }, - Function = { icon = "", hl = "@function" }, - Variable = { icon = "", hl = "@constant" }, - Constant = { icon = "", hl = "@constant" }, - String = { icon = "𝓐", hl = "@string" }, - Number = { icon = "#", hl = "@number" }, - Boolean = { icon = "⊨", hl = "@boolean" }, - Array = { icon = "󰅪", hl = "@constant" }, - Object = { icon = "⦿", hl = "@type" }, - Key = { icon = "🔐", hl = "@type" }, - Null = { icon = "NULL", hl = "@type" }, - EnumMember = { icon = "", hl = "@field" }, - Struct = { icon = "𝓢", hl = "@type" }, - Event = { icon = "🗲", hl = "@type" }, - Operator = { icon = "+", hl = "@operator" }, - TypeParameter = { icon = "𝙏", hl = "@parameter" }, - Component = { icon = "󰅴", hl = "@function" }, - Fragment = { icon = "󰅴", hl = "@constant" }, - -- ccls - TypeAlias = { icon = ' ', hl = '@type' }, - Parameter = { icon = ' ', hl = '@parameter' }, - StaticMethod = { icon = ' ', hl = '@function' }, - Macro = { icon = ' ', hl = '@macro' }, + -- Symbols to ignore. + -- Possible values are the Keys in the icons table below. + blacklist = {}, + -- Changed in this fork to fix deprecated icons not showing. + icons = { + File = { icon = "󰈔", hl = "@text.uri" }, + Module = { icon = "󰆧", hl = "@namespace" }, + Namespace = { icon = "󰅪", hl = "@namespace" }, + Package = { icon = "󰏗", hl = "@namespace" }, + Class = { icon = "𝓒", hl = "@type" }, + Method = { icon = "ƒ", hl = "@method" }, + Property = { icon = "", hl = "@method" }, + Field = { icon = "󰆨", hl = "@field" }, + Constructor = { icon = "", hl = "@constructor" }, + Enum = { icon = "ℰ", hl = "@type" }, + Interface = { icon = "󰜰", hl = "@type" }, + Function = { icon = "", hl = "@function" }, + Variable = { icon = "", hl = "@constant" }, + Constant = { icon = "", hl = "@constant" }, + String = { icon = "𝓐", hl = "@string" }, + Number = { icon = "#", hl = "@number" }, + Boolean = { icon = "⊨", hl = "@boolean" }, + Array = { icon = "󰅪", hl = "@constant" }, + Object = { icon = "⦿", hl = "@type" }, + Key = { icon = "🔐", hl = "@type" }, + Null = { icon = "NULL", hl = "@type" }, + EnumMember = { icon = "", hl = "@field" }, + Struct = { icon = "𝓢", hl = "@type" }, + Event = { icon = "🗲", hl = "@type" }, + Operator = { icon = "+", hl = "@operator" }, + TypeParameter = { icon = "𝙏", hl = "@parameter" }, + Component = { icon = "󰅴", hl = "@function" }, + Fragment = { icon = "󰅴", hl = "@constant" }, + -- Added ccls symbols in this fork + TypeAlias = { icon = ' ', hl = '@type' }, + Parameter = { icon = ' ', hl = '@parameter' }, + StaticMethod = { icon = ' ', hl = '@function' }, + Macro = { icon = ' ', hl = '@macro' }, + }, }, } < -To find out exactly what some of the options do, check out the +To find out exactly what some of the options do, please see the |symbols-outline-recipes| section of the readme at the bottom for screen-recordings. @@ -526,39 +579,6 @@ COMMANDS *symbols-outline-symbols-outline.nvim-commands* With bang, it can be understood as the converse of `focus_location`. -LUA API ~ - ->lua - require'symbols-outline' -< - -- setup(opts) -- **toggle_outline(opts)** - Toggle opening/closing of outline window. - If `opts.focus_outline=false`, keep focus on previous window. -- **open_outline(opts)** - Open the outline window. - If `opts.focus_outline=false`, keep focus on previous window. -- **close_outline()** - Close the outline window. -- **focus_toggle()** - Toggle cursor focus between code and outline window. -- **focus_outline()** - Focus cursor on the outline window. -- **focus_code()** - Focus cursor on the window which the outline is derived from. -- **is_open()** - Return whether the outline window is open. -- **show_status()** - Display current provider and outline window status in the messages area. -- **has_provider()** - Returns whether a provider is available for current window. -- **follow_cursor(opts)** - Go to corresponding node in outline based on cursor position in code, and focus - on the outline window. - With `opts.focus_outline=false`, cursor focus will remain on code window. - - DEFAULT KEYMAPS *symbols-outline-symbols-outline.nvim-default-keymaps* These mappings are active for the outline window. @@ -592,38 +612,96 @@ HIGHLIGHTS *symbols-outline-symbols-outline.nvim-highlights* Pmenu Highlight of the preview popup windows SymbolsOutlineConnector Highlight of the table connectors Comment Highlight of the info virtual text +Note that some highlights are configurable such as the preview window border +and background. Please see |symbols-outline-configuration-options|. + + +LUA API *symbols-outline-symbols-outline.nvim-lua-api* + +Symbols-outline provides the following public API for use in lua. + +>lua + require'symbols-outline' +< + +- setup(opts) +- **toggle_outline(opts)** + Toggle opening/closing of outline window. + If `opts.focus_outline=false`, keep focus on previous window. +- **open_outline(opts)** + Open the outline window. + If `opts.focus_outline=false`, keep focus on previous window. +- **close_outline()** + Close the outline window. +- **focus_toggle()** + Toggle cursor focus between code and outline window. +- **focus_outline()** + Focus cursor on the outline window. +- **focus_code()** + Focus cursor on the window which the outline is derived from. +- **is_open()** + Return whether the outline window is open. +- **show_status()** + Display current provider and outline window status in the messages area. +- **has_provider()** + Returns whether a provider is available for current window. +- **follow_cursor(opts)** + Go to corresponding node in outline based on cursor position in code, and focus + on the outline window. + With `opts.focus_outline=false`, cursor focus will remain on code window. + + +TIPS *symbols-outline-symbols-outline.nvim-tips* + +- To open the outline but don’t focus on it, you can use `:SymbolsOutline!` or + `:SymbolsOutlineOpen`. + This is useful in autocmds, say you have a filetype that, whenever a buffer + with that filetype is opened you want to open the outline. +- After navigating around in the outline window, you can use `` (default + mapping for `restore_location`) to go back to the corresponding outline + location based on the code location. + RECIPES *symbols-outline-symbols-outline.nvim-recipes* Behaviour you may want to achieve and the combination of configuration options to achieve it. +Code snippets in this section are to be placed in `.setup({ })` directly +unless specified otherwise. + **Unfold all others except currently hovered item** >lua - autofold_depth = 1, - auto_unfold_hover = true, + symbol_folding = { + autofold_depth = 1, + auto_unfold_hover = true, + }, < -Any other recipes you think others may also find useful? Feel free to open a -PR. - **Use outline window as a quick-jump window** >lua - auto_preview = true, + preview_window = { + auto_preview = true, + }, < https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/a473d791-d1b9-48e9-917f-b816b564a645 +Note that in the recording I have `preview_window.open_hover_on_preview = +false`. + Alternatively, if you want to automatically navigate to the corresponding code -location and not use the preview window: +location directly and not use the preview window: >lua - auto_goto = true, + outline_window = { + auto_goto = true, + }, < This feature was added by @stickperson in an upstream PR 🙌 @@ -634,22 +712,34 @@ https://github.com/hedyhli/symbols-outline.nvim/assets/50042066/3d06e342-97ac-40 Or, you can use keys `` and `` to achieve the same effect, whilst not having `auto_goto` on by default. +This feature is newly added in this fork. + **Hide the extra details after each symbol name** >lua - show_symbol_details = false, + outline_items = { + show_symbol_details = false, + }, < **Show line numbers next to each symbol to jump to that symbol quickly** +This feature is newly added in this fork. + >lua - show_symbol_lineno = true, + outline_items = { + show_symbol_lineno = false, + }, < -The default highlight group is `LineNr`. +The default highlight group for the line numbers is `LineNr`. +------------------------------------------------------------------------------ +Any other recipes you think others may also find useful? Feel free to open a +PR. + ============================================================================== 3. Links *symbols-outline-links*