docs: improve documentation clarity and organization

* Restructure prerequisites section into Required and Optional * Clarify context documentation with more detailed descriptions * Add missing git/lynx dependency information * Enhance readability of context input descriptions * Fix incorrect function parameter documentation * Make context parameter handling more consistent Signed-off-by: Tomas Slusny <[email protected]>
CopilotC-Nvim · Nov 29, 2024 · 40fbf7a · 40fbf7a
1 parent 121475d
commit 40fbf7a
Show file tree

Hide file tree

Showing 5 changed files with 99 additions and 63 deletions.
diff --git a/README.md b/README.md
@@ -16,7 +16,6 @@
   - [Lazy.nvim](#lazy.nvim)
   - [Vim-Plug](#vim-plug)
   - [Manual](#manual)
-  - [Post-Installation](#post-installation)
 - [Usage](#usage)
   - [Commands](#commands)
   - [Chat Mappings](#chat-mappings)
@@ -38,19 +37,25 @@
 
 ## Prerequisites
 
-Ensure you have the following installed:
+- [Neovim 0.9.5+](https://neovim.io/)
+  - Older versions are not supported, and for best compatibility 0.10.0+ is preferred
+- [curl](https://curl.se/)
+  - 8.0.0+ is recommended for best compatibility
+  - Should be installed by default on most systems and also shipped with Neovim
 
-- **Neovim stable (0.9.5) or nightly**.
+Also make sure [Copilot chat in the IDE](https://github.com/settings/copilot) setting is enabled in GitHub settings.
 
-Verify "[Copilot chat in the IDE](https://github.com/settings/copilot)" is enabled.
-
-Optional:
+**Optional:**
 
 - [tiktoken_core](https://github.com/gptlang/lua-tiktoken)
   - Used for more accurate token counting
-  - Install via luarocks: `sudo luarocks install --lua-version 5.1 tiktoken_core`
-  - Alternatively, download a pre-built binary from [lua-tiktoken releases](https://github.com/gptlang/lua-tiktoken/releases). You can check your Lua PATH in Neovim by doing `:lua print(package.cpath)`. Save the binary as `tiktoken_core.so` in any of the given paths.
   - For Arch Linux users, you can install [`luajit-tiktoken-bin`](https://aur.archlinux.org/packages/luajit-tiktoken-bin) or [`lua51-tiktoken-bin`](https://aur.archlinux.org/packages/lua51-tiktoken-bin) from aur
+  - Alternatively, install via luarocks: `sudo luarocks install --lua-version 5.1 tiktoken_core`
+  - Alternatively, download a pre-built binary from [lua-tiktoken releases](https://github.com/gptlang/lua-tiktoken/releases). You can check your Lua PATH in Neovim by doing `:lua print(package.cpath)`. Save the binary as `tiktoken_core.so` in any of the given paths.
+- [git](https://git-scm.com/)
+  - Used for fetching git diffs for `git` context
+  - For Arch Linux users, you can install [`git`](https://archlinux.org/packages/extra/x86_64/git) from the official repositories
+  - For other systems, use your package manager to install `git`. For windows use the installer provided from git site
 - [lynx](https://lynx.invisible-island.net/)
   - Used for fetching textual representation of URLs for `url` context
   - For Arch Linux users, you can install [`lynx`](https://archlinux.org/packages/extra/x86_64/lynx) from the official repositories
@@ -276,13 +281,17 @@ Any amount of context can be added to the prompt.
 If context supports input, you can set the input in the prompt by using `:` followed by the input (or pressing `complete` key after `:`).  
 Default contexts are:
 
-- `buffer` - Includes specified buffer in chat context (default current). Supports input.
-- `buffers` - Includes all buffers in chat context (default listed). Supports input.
+- `buffer` - Includes specified buffer in chat context. Supports input (default current).
+- `buffers` - Includes all buffers in chat context. Supports input (default listed).
 - `file` - Includes content of provided file in chat context. Supports input.
-- `files` - Includes all non-hidden files in the current workspace in chat context. By default includes only filenames, includes also content with `full` input. Including all content can be slow on big workspaces so use with care. Supports input.
-- `git` - Includes current git diff in chat context (default unstaged). Supports input.
-- `register` - Includes content of specified register in chat context (default `+`, e.g system clipboard). Supports input.
-- `url` - Includes content of provided URL in chat context. Requires `lynx` (see requirements). Supports input.
+- `files` - Includes all non-hidden files in the current workspace in chat context. Supports input (default list).
+  - `files:list` - Only lists file names.
+  - `files:content` - Includes file content for each file found. Can be slow on large workspaces, use with care.
+- `git` - Requires `git`. Includes current git diff in chat context. Supports input (default unstaged).
+  - `git:unstaged` - Includes unstaged changes in chat context.
+  - `git:staged` - Includes staged changes in chat context.
+- `url` - Requires `lynx`. Includes content of provided URL in chat context. Supports input.
+- `register` - Includes contents of register in chat context. Supports input (default +, e.g clipboard).
 
 You can define custom contexts like this:
 
@@ -498,10 +507,10 @@ Also see [here](/lua/CopilotChat/config.lua):
     git = {
       -- see config.lua for implementation
     },
-    register = {
+    url = {
       -- see config.lua for implementation
     },
-    url = {
+    register = {
       -- see config.lua for implementation
     },
   },

diff --git a/lua/CopilotChat/config.lua b/lua/CopilotChat/config.lua
@@ -146,7 +146,7 @@ return {
   -- default contexts
   contexts = {
     buffer = {
-      description = 'Includes specified buffer in chat context (default current). Supports input.',
+      description = 'Includes specified buffer in chat context. Supports input (default current).',
       input = function(callback)
         vim.ui.select(
           vim.tbl_map(
@@ -169,13 +169,14 @@ return {
         )
       end,
       resolve = function(input, source)
+        input = input and tonumber(input) or source.bufnr
         return {
-          context.buffer(input and tonumber(input) or source.bufnr),
+          context.buffer(input),
         }
       end,
     },
     buffers = {
-      description = 'Includes all buffers in chat context (default listed). Supports input.',
+      description = 'Includes all buffers in chat context. Supports input (default listed).',
       input = function(callback)
         vim.ui.select({ 'listed', 'visible' }, {
           prompt = 'Select buffer scope> ',
@@ -212,33 +213,58 @@ return {
       end,
     },
     files = {
-      description = 'Includes all non-hidden files in the current workspace in chat context. By default includes only filenames, includes also content with `full` input. Including all content can be slow on big workspaces so use with care. Supports input.',
+      description = 'Includes all non-hidden files in the current workspace in chat context. Supports input (default list).',
       input = function(callback)
-        vim.ui.select({ 'list', 'full' }, {
+        local choices = utils.kv_list({
+          list = 'Only lists file names',
+          full = 'Includes file content for each file found. Can be slow on large workspaces, use with care.',
+        })
+
+        vim.ui.select(choices, {
           prompt = 'Select files content> ',
-        }, callback)
+          format_item = function(choice)
+            return choice.key .. ' - ' .. choice.value
+          end,
+        }, function(choice)
+          callback(choice and choice.key)
+        end)
       end,
       resolve = function(input, source)
         return context.files(source.winnr, input == 'full')
       end,
     },
     git = {
-      description = 'Includes current git diff in chat context (default unstaged). Supports input.',
+      description = 'Requires `git`. Includes current git diff in chat context. Supports input (default unstaged).',
       input = function(callback)
         vim.ui.select({ 'unstaged', 'staged' }, {
           prompt = 'Select diff type> ',
         }, callback)
       end,
       resolve = function(input, source)
+        input = input or 'unstaged'
         return {
           context.gitdiff(input, source.winnr),
         }
       end,
     },
+    url = {
+      description = 'Requires `lynx`. Includes content of provided URL in chat context. Supports input.',
+      input = function(callback)
+        vim.ui.input({
+          prompt = 'Enter URL> ',
+          default = 'https://',
+        }, callback)
+      end,
+      resolve = function(input)
+        return {
+          context.url(input),
+        }
+      end,
+    },
     register = {
-      description = 'Includes contents of register in chat context (default +, e.g clipboard). Supports input.',
+      description = 'Includes contents of register in chat context. Supports input (default +, e.g clipboard).',
       input = function(callback)
-        local registers = {
+        local choices = utils.kv_list({
           ['+'] = 'synchronized with the system clipboard',
           ['*'] = 'synchronized with the selection clipboard',
           ['"'] = 'last deleted, changed, or yanked content',
@@ -250,43 +276,24 @@ return {
           ['#'] = 'alternate buffer',
           ['='] = 'result of an expression',
           ['/'] = 'last search pattern',
-        }
+        })
 
-        vim.ui.select(
-          vim.tbl_map(function(k)
-            return { id = k, name = k .. ' - ' .. (registers[k] or '') }
-          end, vim.tbl_keys(registers)),
-          {
-            prompt = 'Select a register> ',
-            format_item = function(item)
-              return item.name
-            end,
-          },
-          function(choice)
-            callback(choice and choice.id)
-          end
-        )
+        vim.ui.select(choices, {
+          prompt = 'Select a register> ',
+          format_item = function(choice)
+            return choice.key .. ' - ' .. choice.value
+          end,
+        }, function(choice)
+          callback(choice and choice.key)
+        end)
       end,
       resolve = function(input)
+        input = input or '+'
         return {
           context.register(input),
         }
       end,
     },
-    url = {
-      description = 'Includes content of provided URL in chat context. Requires `lynx`. Supports input.',
-      input = function(callback)
-        vim.ui.input({
-          prompt = 'Enter URL> ',
-          default = 'https://',
-        }, callback)
-      end,
-      resolve = function(input)
-        return {
-          context.url(input),
-        }
-      end,
-    },
   },
 
   -- default prompts

diff --git a/lua/CopilotChat/context.lua b/lua/CopilotChat/context.lua
@@ -307,7 +307,7 @@ end
 
 --- Get list of all files in workspace
 ---@param winnr number?
----@param with_content boolean?
+---@param with_content boolean
 ---@return table<CopilotChat.context.embed>
 function M.files(winnr, with_content)
   local cwd = utils.win_cwd(winnr)
@@ -366,9 +366,13 @@ function M.files(winnr, with_content)
 end
 
 --- Get the content of a file
----@param filename string
+---@param filename? string
 ---@return CopilotChat.context.embed?
 function M.file(filename)
+  if not filename or filename == '' then
+    return nil
+  end
+
   async.util.scheduler()
   local ft = utils.filetype(filename)
   if not ft then
@@ -379,11 +383,10 @@ function M.file(filename)
 end
 
 --- Get the content of a buffer
----@param bufnr? number
+---@param bufnr number
 ---@return CopilotChat.context.embed?
 function M.buffer(bufnr)
   async.util.scheduler()
-  bufnr = bufnr or vim.api.nvim_get_current_buf()
 
   if not utils.buf_valid(bufnr) then
     return nil
@@ -405,6 +408,10 @@ end
 ---@param url string
 ---@return CopilotChat.context.embed?
 function M.url(url)
+  if not url or url == '' then
+    return nil
+  end
+
   local content = url_cache[url]
   if not content then
     local out = utils.system({ 'lynx', '-dump', url })
@@ -423,11 +430,10 @@ function M.url(url)
 end
 
 --- Get current git diff
----@param type string?
+---@param type string
 ---@param winnr number
 ---@return CopilotChat.context.embed?
 function M.gitdiff(type, winnr)
-  type = type or 'unstaged'
   local cwd = utils.win_cwd(winnr)
   local cmd = {
     'git',
@@ -452,10 +458,9 @@ function M.gitdiff(type, winnr)
 end
 
 --- Return contents of specified register
----@param register string?
+---@param register string
 ---@return CopilotChat.context.embed?
 function M.register(register)
-  register = register or '+'
   local lines = vim.fn.getreg(register)
   if not lines or lines == '' then
     return nil

diff --git a/lua/CopilotChat/ui/debug.lua b/lua/CopilotChat/ui/debug.lua
@@ -24,7 +24,7 @@ local function build_debug_info()
     '',
   }
 
-  local buf = context.buffer()
+  local buf = context.buffer(0)
   if buf then
     if buf.symbols then
       table.insert(lines, 'Current buffer symbols:')

diff --git a/lua/CopilotChat/utils.lua b/lua/CopilotChat/utils.lua
@@ -162,6 +162,21 @@ function M.debounce(id, fn, delay)
   M.timers[id] = vim.defer_fn(fn, delay)
 end
 
+--- Create key-value list from table
+---@param tbl table The table
+---@return table
+function M.kv_list(tbl)
+  local result = {}
+  for k, v in pairs(tbl) do
+    table.insert(result, {
+      key = k,
+      value = v,
+    })
+  end
+
+  return result
+end
+
 --- Check if a buffer is valid
 ---@param bufnr number? The buffer number
 ---@return boolean