From 40fcae99538489df2ec5fc0465273865ee3b5d0f Mon Sep 17 00:00:00 2001
From: Oli Morris
Date: Tue, 16 Jan 2024 22:17:19 +0000
Subject: [PATCH] docs: add neovim documentation
---
README.md | 2 +-
doc/codecompanion.txt | 295 ++++++++++++++++++++++++++++++++++++++++++
2 files changed, 296 insertions(+), 1 deletion(-)
create mode 100644 doc/codecompanion.txt
diff --git a/README.md b/README.md
index 37d7d54c..e98b783f 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
-
+
diff --git a/doc/codecompanion.txt b/doc/codecompanion.txt
new file mode 100644
index 00000000..786d50f7
--- /dev/null
+++ b/doc/codecompanion.txt
@@ -0,0 +1,295 @@
+*codecompanion.txt* Use the OpenAI APIs directly in Neovim
+
+==============================================================================
+Table of Contents *codecompanion-table-of-contents*
+
+ - Features |codecompanion-features|
+ - Requirements |codecompanion-requirements|
+ - Installation |codecompanion-installation|
+ - Configuration |codecompanion-configuration|
+ - Usage |codecompanion-usage|
+ - Helpers |codecompanion-helpers|
+
+FEATURES *codecompanion-features*
+
+- Chat with the OpenAI APIs via a Neovim buffer
+- Built in actions for specific language prompts, LSP error fixes and inline code generation
+- Create your own custom actions for Neovim which hook into OpenAI
+- Save and restore your chats
+- Async execution for improved performance
+
+
+REQUIREMENTS *codecompanion-requirements*
+
+- An API key from OpenAI (get one here )
+- The `curl` library installed
+- Neovim 0.9.0 or greater
+
+
+INSTALLATION *codecompanion-installation*
+
+- Set your OpenAI API Key as an environment variable in your shell (default name: `OPENAI_API_KEY`)
+- Install the plugin with your package manager of choice:
+
+>lua
+ -- Lazy.nvim
+ {
+ "olimorris/codecompanion.nvim",
+ dependencies = {
+ {
+ "stevearc/dressing.nvim", -- Optional: Improves the default Neovim UI
+ opts = {},
+ },
+ },
+ cmd = { "CodeCompanionChat", "CodeCompanionActions" },
+ config = true
+ }
+
+ -- Packer.nvim
+ use({
+ "olimorris/codecompanion.nvim",
+ config = function()
+ require("codecompanion").setup()
+ end,
+ requires = {
+ "stevearc/dressing.nvim"
+ }
+ })
+<
+
+
+CONFIGURATION *codecompanion-configuration*
+
+The plugin comes with the following defaults:
+
+>lua
+ {
+ api_key = "OPENAI_API_KEY", -- Your OpenAI API key
+ org_api_key = "OPENAI_ORG_KEY", -- Your organisation OpenAI API key
+ base_url = "https://api.openai.com", -- The URL to use for the API requests
+ ai_settings = {
+ -- Default settings for the Completions API
+ -- See https://platform.openai.com/docs/api-reference/chat/create
+ models = {
+ chat = "gpt-4-1106-preview",
+ author = "gpt-4-1106-preview",
+ advisor = "gpt-4-1106-preview",
+ },
+ temperature = 1,
+ top_p = 1,
+ stop = nil,
+ max_tokens = nil,
+ presence_penalty = 0,
+ frequency_penalty = 0,
+ logit_bias = nil,
+ user = nil,
+ },
+ conversations = {
+ auto_save = true, -- Once a conversation is created/loaded, automatically save it
+ save_dir = vim.fn.stdpath("data") .. "/codecompanion/conversations",
+ },
+ display = { -- How to display `advisor` outputs
+ type = "popup", -- popup|split
+ split = "horizontal" -- horizontal|vertical
+ height = 0.7,
+ width = 0.8,
+ },
+ log_level = "ERROR", -- One of: TRACE, DEBUG, ERROR
+ send_code = true, -- Send your code to OpenAI
+ show_token_count = true, -- Show the token count for the current chat
+ use_default_actions = true, -- The actions that appear in the action palette
+ }
+<
+
+Modify these settings via the `opts` table in Lazy.nvim or by calling the
+`require("codecompanion").setup()` function in Packer.
+
+
+ **Note**The `send_code` option can prevent any visual selections from being
+ sent to OpenAI for processing as part of any `advisor` or `author` actions
+
+USAGE *codecompanion-usage*
+
+The plugin has a number of commands:
+
+- `CodeCompanionChat` - To open up a new chat buffer
+- `CodeCompanionActions` - To open up the action selector window
+- `CodeCompanionSaveConversationAs` - Saves a chat buffer as a conversation
+
+They can be assigned to keymaps with:
+
+>lua
+ vim.api.nvim_set_keymap("n", "", "CodeCompanionActions", { noremap = true, silent = true })
+ vim.api.nvim_set_keymap("v", "", "CodeCompanionActions", { noremap = true, silent = true })
+ vim.api.nvim_set_keymap("n", "a", "CodeCompanionChat", { noremap = true, silent = true })
+<
+
+
+ **Note**For some actions, visual mode allows your selection to be sent directly
+ to the chat buffer or OpenAI themselves in the case of `author` actions
+
+THE ACTION PALETTE ~
+
+The Action Palette, opened via `:CodeCompanionActions`, contains all of the
+actions and their associated strategies for the plugin. It’s the fastest way
+to start leveraging CodeCompanion. Depending on whether you’re in _normal_ or
+_visual_ mode will affect the options that are available in the palette.
+
+You may add your own actions into the palette by altering your configuration:
+
+>lua
+ require("codecompanion").setup({
+ actions = {
+ {
+ name = "My new action",
+ strategy = "chat"
+ description = "Some cool action you can do",
+ }
+ }
+ })
+<
+
+
+ **Note**We describe how to do this in detail within the `RECIPES.md` file
+Or, if you wish to turn off the default actions, set `use_default_actions =
+false` in your config.
+
+
+THE CHAT BUFFER ~
+
+The Chat Buffer is where you can converse with OpenAI, directly from Neovim. It
+behaves as a regular markdown buffer with some clever additions. When the
+buffer is written, autocmds trigger the sending of its content to the OpenAI
+API in the form of prompts. These prompts are segmented by H1 headers into
+`user` and `assistant` (see OpenAI’s Chat Completions API
+
+for more on this). When a response is received, it is then streamed back into
+the buffer. The result is that you experience the feel of conversing with
+ChatGPT, from within Neovim.
+
+
+ **Note**You can cancel a request at any point by pressing `q`.
+At the very top of the Chat Buffer are the parameters which can be changed to
+affect the API’s response back to you. You can find more detail about them by
+moving the cursor over them or referring to the Chat Completions reference
+guide . The parameters can
+be tweaked and modified throughout the conversation.
+
+Chat Buffers are not automatically saved into sessions owing to them being an
+`acwrite` buftype (|buftype|). However the plugin allows for this via the
+notion of Conversations. Simply run `:CodeCompanionSaveConversationAs` in the
+buffer you wish to save. Conversations can then be restored via the Action
+Palette and the _Load conversations_ actions. When a conversation is saved or
+loaded it will automatically save to disk.
+
+
+IN-BUILT ACTIONS ~
+
+The plugin comes with a number of in-built actions
+
+which aim to improve your Neovim workflow. Actions make use of strategies which
+are abstractions built around Neovim and OpenAI functionality. Before we dive
+in to the actions, it’s worth explaining what each of the strategies do:
+
+- `chat` - A strategy for opening up a chat buffer allowing the user to converse directly with OpenAI
+- `author` - A strategy for allowing OpenAI responses to be written directly into a Neovim buffer
+- `advisor` - A strategy for outputting OpenAI responses into a split or a popup, alongside a Neovim buffer
+
+
+CHAT AND CHAT AS
+
+Both of these actions utilise the `chat` strategy. The `Chat` action opens up a
+fresh chat buffer. The `Chat as` action allows for persona based context to be
+set in the chat buffer allowing for better and more detailed responses from
+OpenAI.
+
+
+ **Note**Both of these actions allow for visually selected code to be sent to
+ the chat buffer as code blocks.
+
+CODE AUTHOR
+
+This action utilises the `author` strategy. This action can be useful for
+generating code or even refactoring a visual selection based on a prompt by the
+user. The action is designed to write code for the buffer filetype that it is
+initated in, or, if run from a terminal prompt, to write commands.
+
+
+CODE ADVISOR
+
+As the name suggests, this action provides advice on a visual selection of code
+and utilises the `advisor` strategy. It uses the `display` configuration option
+to output the response from OpenAI into a split or a popup. Inevitably, the
+response back from OpenAI may lead to more questions. Pressing `c` in the
+advisor buffer will take the conversation to a chat buffer. Pressing `q` will
+close the buffer.
+
+
+ **Note**For some users, the sending of code to OpenAI may not be an option. In
+ those instances, you can set `send_code = false` in your config.
+
+LSP ASSISTANT
+
+Taken from the fantastic Wtf.nvim
+plugin, this action provides advice (utilising the `advisor` strategy) on any
+LSP diagnostics which occur across visually selected lines and how they can be
+fixed. Again, the `send_code = false` value can be set in your config to only
+send diagnostic messages to OpenAI.
+
+
+HELPERS *codecompanion-helpers*
+
+
+HOOKS / USER EVENTS ~
+
+The plugin fires events at the start and the conclusion of an API request. A
+user can hook into these as follows:
+
+>lua
+ local group = vim.api.nvim_create_augroup("CodeCompanionHooks", {})
+
+ vim.api.nvim_create_autocmd({ "User" }, {
+ pattern = "CodeCompanion",
+ group = group,
+ callback = function(request)
+ print(request.data.status) -- outputs "started" or "finished"
+ end,
+ })
+<
+
+
+ **Note**The author uses these to display an icon in his statusline.
+
+HEIRLINE.NVIM ~
+
+If you use the fantastic Heirline.nvim
+ plugin, consider the following
+snippet to display an icon in the statusline whilst CodeCompanion is speaking
+to the LLM:
+
+>lua
+ local OpenAI = {
+ static = {
+ processing = false,
+ },
+ update = {
+ "User",
+ pattern = "CodeCompanion",
+ callback = function(self, args)
+ self.processing = (args.data.status == "started")
+ vim.cmd("redrawstatus")
+ end,
+ },
+ {
+ condition = function(self)
+ return self.processing
+ end,
+ provider = " ",
+ hl = { fg = "yellow" },
+ },
+ }
+<
+
+Generated by panvimdoc
+
+vim:tw=78:ts=8:noet:ft=help:norl: