branch: elpa/aidermacs
commit 75fdfc4a7d6e484816a83f5fbfc28169c5c87956
Author: Mingde (Matthew) Zeng (aider) <matthew...@posteo.net>
Commit: Mingde (Matthew) Zeng (aider) <matthew...@posteo.net>
docs: Rewrite README with comprehensive usage guide for Aidermacs
---
README.org | 96 +++++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 67 insertions(+), 29 deletions(-)
diff --git a/README.org b/README.org
index 54898ea399..9d15caa05d 100644
--- a/README.org
+++ b/README.org
@@ -98,32 +98,70 @@ When using the comint backend, you can customize the key
binding for multiline i
This key allows you to enter multiple lines without sending the command to
Aider. Press =RET= normally to send the command.
-* Features
-
-** Session Management
-- Create repository-specific Aidermacs sessions
-- Switch between multiple AI sessions
-- Toggle between window and frame views
-
-** Code Operations
-- Add files in read-write or read-only mode
-- Refactor selected regions or functions
-- Implement TODOs from comments
-- Generate and fix unit tests
-- Analyze and explain code
-
-** Helm Integration
-For fuzzy command history searching.
-
-** Prompt Management
-Access repository-specific prompt files with =C-c a p= for organizing and
reusing prompts.
-
-* Development Workflow
-
-1. Start an Aidermacs session (=aidermacs-run-aider=)
-2. Add relevant files to the session
-3. Implement or modify code using:
- - =aidermacs-implement-todo= for new code
- - =aidermacs-function-or-region-refactor= for existing code
-4. Generate and run tests
-5. Refine the implementation through additional prompts or manual edits
+* Usage Guide
+
+This section provides a step-by-step guide on how to use Aidermacs for
AI-assisted pair programming in Emacs.
+
+** 1. Start an Aidermacs Session
+
+- Use the command =aidermacs-run-aidermacs= or press =C-c a a= (if using the
default keybindings) to start an Aidermacs session.
+- This will open a new buffer named =*aidermacs:your-repo-name*= where you can
interact with the AI.
+- If you want to use a specific AI model, you can customize the
=aidermacs-args= variable in your Emacs configuration (see "Installation"
section).
+- You can also select a model interactively by using the
=aidermacs-change-model= command or pressing =C-c a o=.
+
+** 2. Add Files to the Session
+
+- To provide context to the AI, you need to add relevant files to the
Aidermacs session.
+- You can add the current file using =aidermacs-add-current-file= or press
=C-c a A c=.
+- To add the current file in read-only mode, use
=aidermacs-current-file-read-only= or press =C-c a A f=. This prevents the AI
from modifying the file.
+- You can add all files in the current window using
=aidermacs-add-files-in-current-window= or press =C-c a A w=.
+- To add all files with the same suffix as the current file in the current
directory, use =aidermacs-add-same-type-files-under-dir= or press =C-c a A d=.
+- If you are in =dired-mode=, you can add multiple marked files using
=aidermacs-batch-add-dired-marked-files= or press =C-c a A b=.
+
+** 3. Interact with the AI
+
+- Once you have added the relevant files, you can start interacting with the
AI.
+- You can ask general questions about the code using =aidermacs-ask-question=
or press =C-c a D a=.
+- To ask a general question without any context, use
=aidermacs-general-question= or press =C-c a O Q=.
+- You can also use =aidermacs-code-change= or press =C-c a C c= to ask the AI
to make specific code changes.
+- To refactor a function or region, use
=aidermacs-function-or-region-refactor= or press =C-c a C r=.
+- To implement TODO comments, use =aidermacs-implement-todo= or press =C-c a C
i=.
+- To explain a function or region, use =aidermacs-function-or-region-explain=
or press =C-c a D e=.
+- To explain the symbol under the point, use
=aidermacs-explain-symbol-under-point= or press =C-c a D p=.
+- To generate unit tests, use =aidermacs-write-unit-test= or press =C-c a C U=.
+- To fix a failing test, use =aidermacs-fix-failing-test-under-cursor= or
press =C-c a C T=.
+- To have the AI continue with the last task, use =aidermacs-go-ahead= or
press =C-c a D y=.
+- To get help on a specific command, use =aidermacs-help= or press =C-c a O h=.
+- To start an architectural discussion, use =aidermacs-architect-discussion=
or press =C-c a C t=.
+- To debug an exception, use =aidermacs-debug-exception= or press =C-c a D D=.
+- To undo the last change made by Aidermacs, use =aidermacs-undo-last-change=
or press =C-c a C u=.
+
+** 4. Send Code Blocks
+
+- You can send code blocks to the AI using the following commands:
+ - =aidermacs-send-line-or-region= or press =C-c C-n= or =C-<return>=: Sends
the current line or the selected region line by line.
+ - =aidermacs-send-block-or-region= or press =C-c C-c=: Sends the current
block (paragraph) or the selected region as a whole.
+
+** 5. Manage the Aidermacs Session
+
+- You can switch to the Aidermacs buffer using =aidermacs-switch-to-buffer= or
press =C-c a B b= or =C-c C-z=.
+- To clear the Aidermacs buffer, use =aidermacs-clear= or press =C-c a B c=.
+- To reset the Aidermacs session, use =aidermacs-reset= or press =C-c a B s=.
+- To exit the Aidermacs session, use =aidermacs-exit= or press =C-c a B x=.
+
+** 6. Prompt Files
+
+- You can create a prompt file in the root of your Git repository to store
frequently used prompts.
+- Use the command =aidermacs-open-prompt-file= or press =C-c a O p= to open
the prompt file.
+- The prompt file is a plain text file where you can write your prompts.
+- Each line in the prompt file is treated as a separate prompt.
+- You can use the keybindings defined in =aidermacs-minor-mode-map= to send
prompts from the prompt file to the Aidermacs session.
+
+** 7. Keybindings
+
+- Aidermacs provides a transient menu with keybindings for all available
commands.
+- To open the transient menu, use the command =aidermacs-transient-menu= or
press =C-c a=.
+- The transient menu shows the available commands and their corresponding
keybindings.
+- You can customize the keybindings in your Emacs configuration.
+
+By following these steps, you can effectively use Aidermacs to enhance your
Emacs workflow with AI-powered pair programming.
