Update some docs for 0.2#879
Conversation
Signed-off-by: Emily McMullan <emcmulla@redhat.com>
WalkthroughThis PR updates multiple documentation pages: restructures Getting Started, overhauls Configuration with new settings (Solution Server, Agent Mode, logging/tracing), revises Debug logs guidance, updates Demo Mode cache key and instructions, and performs extensive editorial rewrites to the Custom Rules Integration guide. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant IDE as IDE Extension
participant Analyzer
participant Soln as Solution Server
participant Model as GenAI Provider
User->>IDE: Configure Kai & Analysis settings
User->>IDE: Start RPC Server / Run Analysis
IDE->>Analyzer: Invoke analysis (profiles, labels)
Analyzer-->>IDE: Analysis results
alt Agent Mode enabled
IDE->>Soln: Send context & issues
Soln->>Model: Prompt with traces (optional)
Model-->>Soln: Proposed fixes/solutions
Soln-->>IDE: Fix suggestions
end
IDE-->>User: Review diffs / auto-accept on save (optional)
Note over IDE,Soln: Tracing/logging to cache/trace dirs if enabled
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/debug.md (1)
24-27: Update the example log filenamesWe now steer readers to
analysis_<>.json,analyzer.log, andextension.logat the top of the page, but this bullet still references the retiredkai-analyzer-server.log/kai-rpc-server.log. Please align the example filenames so users look in the right place for diagnostics.- - Logs: Attach any relevant log files (e.g., `kai-analyzer-server.log` or `kai-rpc-server.log`) to help us identify the issue. + - Logs: Attach any relevant log files (e.g., `analyzer.log`, `extension.log`, or `analysis_<timestamp>.json`) to help us identify the issue.
🧹 Nitpick comments (3)
docs/custom_ruleset.md (2)
36-37: Fix the “Analysis” typo“Konveyor Aanlysis View” should read “Konveyor Analysis View” for accuracy and polish. A quick correction prevents confusion in the UI instructions.
-Now you can return to the `Konveyor Aanlysis View` page and start the server. +Now you can return to the `Konveyor Analysis View` page and start the server.
47-58: Correct heading spelling and stray quotes in the YAML exampleThe heading should be “Determining rules”, and the YAML snippets include stray closing quotes/tabs that will produce odd copy/paste results. Cleaning these up keeps the guide professional and copy-ready.
-### Determing rules +### Determining rules @@ - This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts should be used instead." + This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, so use the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts instead. @@ - This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts should be used instead." + This artifact was just an aggregator of some of the Kubernetes model artifacts and had no specific purpose. It is no longer published, so use the io.fabric8:kubernetes-client-api or io.fabric8:kubernetes-openshift-uberjar artifacts instead.docs/configuration.md (1)
58-60: Fix typo in Debug setting description“handilng” should be “handling” to keep the setting description clear.
-#### **Debug: Webview** - -Debug logging for webview message handilng +#### **Debug: Webview** + +Debug logging for webview message handling
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (16)
docs/images/advanced_config.pngis excluded by!**/*.pngdocs/images/custom_rules/add_custom_ruleset.pngis excluded by!**/*.pngdocs/images/custom_rules/running_server.pngis excluded by!**/*.pngdocs/images/custom_rules/search_custom_rules.pngis excluded by!**/*.pngdocs/images/custom_rules/stopped_server.pngis excluded by!**/*.pngdocs/images/demo_mode/kai_demo_mode_search.pngis excluded by!**/*.pngdocs/images/open_settings.pngis excluded by!**/*.pngdocs/images/resolve-issues.pngis excluded by!**/*.pngdocs/images/setup-konveyor-2.pngis excluded by!**/*.pngdocs/images/setup-konveyor.pngis excluded by!**/*.pngdocs/images/start-rpc-server.pngis excluded by!**/*.pngdocs/images/start-server.pngis excluded by!**/*.pngdocs/images/walkthrough-1.pngis excluded by!**/*.pngdocs/images/walkthrough-2.pngis excluded by!**/*.pngdocs/images/walkthrough-3.pngis excluded by!**/*.pngdocs/images/walkthrough-4.pngis excluded by!**/*.png
📒 Files selected for processing (5)
docs/configuration.md(2 hunks)docs/custom_ruleset.md(5 hunks)docs/debug.md(2 hunks)docs/demo_mode.md(1 hunks)docs/getting_started.md(4 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/configuration.md
35-35: Link text should be descriptive
(MD059, descriptive-link-text)
52-52: Link text should be descriptive
(MD059, descriptive-link-text)
56-56: Link text should be descriptive
(MD059, descriptive-link-text)
docs/custom_ruleset.md
21-21: Link text should be descriptive
(MD059, descriptive-link-text)
87-87: Blank line inside blockquote
(MD028, no-blanks-blockquote)
103-103: Hard tabs
Column: 3
(MD010, no-hard-tabs)
104-104: Hard tabs
Column: 3
(MD010, no-hard-tabs)
docs/getting_started.md
17-17: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
62-62: Link text should be descriptive
(MD059, descriptive-link-text)
|  | ||
|
|
||
| The key to use is `conveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache,` but you can change this to wherever you would like to store it. | ||
| The key to use is `konveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache,` but you can change this to wherever you would like to store it. |
There was a problem hiding this comment.
Fix the cache path example punctuation.
The inline example path now includes a trailing comma inside the backticks (/Users/shurley/repos/kai/cache,), which makes the copied path invalid. Please move the comma outside the code span so users don’t accidentally paste an incorrect path.
Apply this diff to correct the example:
-The key to use is `konveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache,` but you can change this to wherever you would like to store it.
+The key to use is `konveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache`, but you can change this to wherever you would like to store it.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The key to use is `konveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache,` but you can change this to wherever you would like to store it. | |
| The key to use is `konveyor.kai.cacheDir`, and the value is an absolute path to a location on your hard drive. In the example, I am putting the cache to `/Users/shurley/repos/kai/cache`, but you can change this to wherever you would like to store it. |
🤖 Prompt for AI Agents
In docs/demo_mode.md around line 32, the inline example path includes a trailing
comma inside the backticks (`/Users/shurley/repos/kai/cache,`) which makes the
copied path invalid; edit the line to move the comma outside the code span so
the backticked path is `/Users/shurley/repos/kai/cache` and the comma follows
after the closing backtick.
| ## Overview | ||
|
|
||
| Before you install Kai, you must: | ||
| #### Before you install Kai, you must: |
There was a problem hiding this comment.
Adjust heading levels to satisfy markdown linting.
Both “Before you install Kai, you must:” and “Running Kai consists of:” were promoted to ####, but the previous heading level is ##, so markdownlint (MD001) requires ###. Bumping them back up by one level keeps the hierarchy valid.
Apply this diff to fix the heading levels:
-#### Before you install Kai, you must:
+### Before you install Kai, you must:
@@
-#### Running Kai consists of:
+### Running Kai consists of:Based on learnings
Also applies to: 30-30
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4
(MD001, heading-increment)
🤖 Prompt for AI Agents
In docs/getting_started.md around lines 17 and 30, the headings "Before you
install Kai, you must:" and "Running Kai consists of:" are currently at level
#### but the previous heading is ##; change those two headings down one level to
### to satisfy markdownlint MD001 and restore proper heading hierarchy.
|
|
||
| - The **solution server**. See [MCP Solution Server setup](../kai_mcp_solution_server/README.md) | ||
| - **Agent mode** for automated analysis with manual review | ||
| - **Demo mode** to use cached responses from the LLM. More details can be found [here](demo_mode.md). |
There was a problem hiding this comment.
Use descriptive link text for demo mode reference.
Markdownlint (MD059) flags “here” as non-descriptive link text. Rename the link to reflect the destination so accessibility and lint checks pass.
Apply this diff to improve the link text:
-- **Demo mode** to use cached responses from the LLM. More details can be found [here](demo_mode.md).
+- **Demo mode** to use cached responses from the LLM. More details can be found in the [Demo Mode guide](demo_mode.md).Based on learnings
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **Demo mode** to use cached responses from the LLM. More details can be found [here](demo_mode.md). | |
| - **Demo mode** to use cached responses from the LLM. More details can be found in the [Demo Mode guide](demo_mode.md). |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
62-62: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
In docs/getting_started.md around line 62, the link text "here" is
non-descriptive and triggers markdownlint MD059; replace the generic "here" link
with descriptive text like "demo mode documentation" (or similar) so the link
reads "**Demo mode** to use cached responses from the LLM. More details can be
found demo mode documentation." and update the link target to (demo_mode.md)
accordingly to satisfy accessibility and lint checks.
1 participant
Summary by CodeRabbit