Auto generate vim docs

doc/outline.txt

@@ -13,6 +13,7 @@ Table of Contents                                  *outline-table-of-contents*
   - Lua API                                                  |outline-lua-api|
   - Tips                                                        |outline-tips|
   - Recipes                                                  |outline-recipes|
+  - Limitations                                          |outline-limitations|
   - Related plugins                                  |outline-related-plugins|
 
 PREREQUISITES                                          *outline-prerequisites*
@@ -95,8 +96,9 @@ configuration.
 - **Node**: An item in the outline view
 - **Fold**: Collapse a collapsible node
 - **Location**: Where in the source file a node is from
-- **Preview**: Show the location of a node in code using a floating window
+- **Preview**: Show the location of a node in code using a floating window.
-- **Peek**: Go to corresponding location in code without leaving outline window
+    Syntax highlighting is provided if treesitter is installed.
+- **Jump/Peek**: Go to corresponding location in code without leaving outline window
 - **Hover**: Cursor currently on the line of a node
 - **Hover symbol**: Displaying a floating window to show symbol information
     provided by provider.
@@ -140,7 +142,7 @@ Show defaults ~
         -- when jumping. false to disable.
         jump_highlight_duration = 300,
         -- Whether to center the cursor line vertically in the screen when
-        -- jumping/focusing. Runs zz.
+        -- jumping/focusing. Executes zz.
         center_on_jump = true,
     
         -- Vim options for the outline window
@@ -148,13 +150,14 @@ Show defaults ~
         show_relative_numbers = false,
         wrap = false,
     
+        -- true/false/'focus_in_outline'/'focus_in_code'.
+        -- The last two means only show cursorline when the focus is in outline/code.
+        -- 'focus_in_outline' can be used if the outline_items.auto_set_cursor
+        -- operations are too distracting due to visual contrast caused by cursorline.
         show_cursorline = true,
         -- Enable this only if you enabled cursorline so your cursor color can
         -- blend with the cursorline, in effect, as if your cursor is hidden
         -- in the outline window.
-        -- This is useful because with cursorline, there isn't really a need
-        -- to know the vertical column position of the cursor and it may even
-        -- be distracting, rendering lineno/guides/icons unreadable.
         -- This makes your line of cursor have the same color as if the cursor
         -- wasn't focused on the outline window.
         -- This feature is experimental.
@@ -177,8 +180,6 @@ Show defaults ~
       },
     
       outline_items = {
-        -- Whether to highlight the currently hovered symbol and all direct parents
-        highlight_hovered_item = true,
         -- Show extra details with the symbols (lsp dependent) as virtual next
         show_symbol_details = true,
         -- Show corresponding line numbers of each symbol on the left column as
@@ -186,6 +187,25 @@ Show defaults ~
         -- 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 and all direct parents
+        highlight_hovered_item = true,
+        -- Whether to automatically set cursor location in outline to match
+        -- location in code when focus is in code. If disabled you can use
+        -- `:OutlineFollow[!]` from any window or `<C-g>` from outline window to
+        -- trigger this manually.
+        auto_set_cursor = true,
+        -- Autocmd events to automatically trigger these operations.
+        auto_update_events = {
+          -- Includes both setting of cursor and highlighting of hovered item.
+          -- The above two options are respected.
+          -- This can be triggered manually through `follow_cursor` lua API,
+          -- :OutlineFollow command, or <C-g>.
+          follow = { 'CursorMoved' },
+          -- Re-request symbols from the provider.
+          -- This can be triggered manually through `refresh_outline` lua API, or
+          -- :OutlineRefresh command.
+          items = { 'InsertLeave', 'WinEnter', 'BufEnter', 'BufWinEnter', 'TabEnter', 'BufWritePost' },
+        },
       },
     
       -- Options for outline guides which help show tree hierarchy of symbols
@@ -254,7 +274,6 @@ Show defaults ~
         hover_symbol = '<C-space>',
         -- Preview location code of the symbol under cursor
         toggle_preview = 'K',
-        -- Symbol actions
         rename_symbol = 'r',
         code_actions = 'a',
         -- These fold actions are collapsing tree nodes, not code folding
@@ -427,8 +446,8 @@ COMMANDS                                                    *outline-commands*
 - **:OutlineFocus**: Toggle focus between outline and code/source window
 - **:OutlineFocusOutline**: Focus on outline
 - **:OutlineFocusCode**: Focus on source window
-- **:OutlineStatus**: Display current provider and outline window status in the
+- **:OutlineStatus**: Display provider and outline window status in a floating
-    messages area
+    window, similar to `:LspInfo`
 - **:OutlineFollow[!]** (✓ bang × mods)
     Go to corresponding node in outline based on cursor position in code, and focus
     on the outline window.
@@ -438,12 +457,23 @@ COMMANDS                                                    *outline-commands*
     whereas this command sets position in outline window to the cursor position of
     code window.
     With bang, it can be understood as the converse of `peek_location`.
+    This is automatically triggered on events
+    `config.outline_items.auto_update_events.follow`.
+    You can also trigger this manually using the `restore_location` keymap (default
+    `<C-g>`) from the outline window.
+- **:OutlineRefresh**
+    Trigger refresh of symbols from provider and update outline items.
+    This is automatically triggered on events
+    `config.outline_items.auto_update_events.refresh`.
 
 
 DEFAULT KEYMAPS                                      *outline-default-keymaps*
 
 These mappings are active only for the outline window.
 
+You can open a floating window showing the following list of keymaps using the
+`?` key by default from the outline window.
+
   Key           Action
   ------------- ----------------------------------------------------
   Esc / q       Close outline
@@ -464,7 +494,7 @@ These mappings are active only for the outline window.
   R             Reset all folding
   Ctrl+k        Go up and peek location
   Ctrl+j        Go down and peek location
-  ?             Show current keymaps as a vim message
+  ?             Show current keymaps in a floating window
 
 HIGHLIGHTS                                                *outline-highlights*
 
@@ -549,13 +579,21 @@ Outline.nvim provides the following public API for use in lua.
 - **is_open()**
     Return whether the outline window is open.
 - **show_status()**
-    Display current provider and outline window status in the messages area.
+    Display provider and outline window status in a floating window.
 - **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.
+    This is automatically called on events
+    `config.outline_items.auto_update_events.follow`.
+- **is_focus_in_outline()**
+    Return whether outline is open and current focus is in outline.
+- **refresh_outline()**
+    Re-request symbols from provider and update outline items.
+    This is automatically called on events
+    `config.outline_items.auto_update_events.refresh`.
 
 
 TIPS                                                            *outline-tips*
@@ -749,6 +787,28 @@ Disable icons for specific kinds, and for others use lspkind:
 
 
 
+LIMITATIONS                                              *outline-limitations*
+
+
+PREVIEW WINDOW ~
+
+Sometimes the preview window could be slow in loading. This could be due to the
+code buffer being large. As of now there are no good solutions in circumventing
+this problem — currently the entire code buffer is read, and then put into
+the preview buffer. If only the required portion to preview is read and set
+instead, there would be highlighting issues (say the calculated starting line
+was within a markdown code block, so what was previously not supposed to be
+code is now highlighted as code).
+
+
+MANY OUTLINES ~
+
+Outline.nvim does not support having multiple outlines attached to different
+buffers as of now. However, this feature is planned
+<https://github.com/hedyhli/outline.nvim/issues/26>, and for now you can use a
+single outline sidebar and have it auto-update whenever you switch buffers.
+
+
 RELATED PLUGINS                                      *outline-related-plugins*
 
 - Aerial.nvim