Update documentation for analysis creation - #107
Conversation
📝 WalkthroughWalkthroughThe documentation adds a demo-instance guide, updates installation verification, revises the analysis workflow, and changes user sidebar routes. ChangesDocumentation workflows
Estimated code review effort: 2 (Simple) | ~15 minutes Sequence Diagram(s)sequenceDiagram
participant User
participant DemoInstanceGuide
participant Hub
User->>DemoInstanceGuide: Follow setup instructions
DemoInstanceGuide->>Hub: Connect data store and run HALTA demo analysis
Hub-->>User: Return analysis results
Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/.vitepress/routes/sidebar/user.tsESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox. 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: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/guide/user/analysis.md`:
- Around line 22-35: Update the documentation around the “Approval,” “Build
Analysis,” “Distribute Analysis,” and “Execution” sections to make approval an
explicit prerequisite before building, either by moving the Approval section
before Step 4 or clearly labeling it as a prerequisite. Revise the Execution
text to state that nodes can start only after approval, a successful build, and
distribution.
In `@src/guide/user/demo.md`:
- Around line 1-19: Remove the Markdown comment-syntax scratchpad at the start
of the guide, including the HTML comment and all reference-definition examples,
so the document begins with Demo Instance workflow content; do not replace it
with unrelated documentation.
- Line 81: Remove the stale TODO comment in the documentation near the
analysis.md reference, since src/guide/user/analysis.md has been updated. Do not
replace it unless there is a specific current, actionable task to record.
- Around line 50-53: Update the preparation step heading and description around
the project workflow so they match the sidebar’s “Submitting a Project Proposal”
terminology and state that a proposal is required before creating an analysis.
Keep the link aligned with the documented proposal-submission workflow, or
explicitly explain when the project becomes available for analysis.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 5baa19f4-bccf-4158-80dd-45b18f47f80c
⛔ Files ignored due to path filters (3)
src/public/images/ui_images/analysis_distribution.pngis excluded by!**/*.pngsrc/public/images/ui_images/analysis_start.pngis excluded by!**/*.pngsrc/public/images/ui_images/hub_add_analysis_from_proposal.pngis excluded by!**/*.png
📒 Files selected for processing (4)
src/.vitepress/routes/sidebar/user.tssrc/guide/deployment/node-installation.mdsrc/guide/user/analysis.mdsrc/guide/user/demo.md
| ### 4. Build Analysis | ||
| Once all nodes have [approved](#approval) the analysis, the **start** button in the **Build** area can be clicked to build the container. | ||
| ### 5. Distribute Analysis | ||
| To distribute the built analysis across the selected nodes, click the **start** button in the **Distribution** area. | ||
| [](/images/ui_images/analysis_distribution.png) | ||
|
|
||
| ## Approval | ||
| ## Approval | ||
| Before the analysis can be built and executed, it must be approved by the nodes you selected during setup. | ||
| Refer to the [Admin Guide](../admin/analysis-review) for detailed information on the approval process. | ||
|
|
||
| ## Execution | ||
| Once approved, the analysis is ready for execution: | ||
|
|
||
| Node Execution | ||
| Each node administrator must manually start the analysis via the node UI. For more details, consult the [Node Guide](../admin/analysis-execution). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make approval, build, and distribution prerequisites explicit.
Line 23 requires node approval before the build, but the Approval section appears after the Build and Distribution steps. Line 33 then says approval alone makes the analysis ready, although the admin execution guide requires a configured and built image before a node can start it. Move Approval before Step 4 or label it as a prerequisite, and state that execution requires approval, a successful build, and distribution.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/guide/user/analysis.md` around lines 22 - 35, Update the documentation
around the “Approval,” “Build Analysis,” “Distribute Analysis,” and “Execution”
sections to make approval an explicit prerequisite before building, either by
moving the Approval section before Step 4 or clearly labeling it as a
prerequisite. Revise the Execution text to state that nodes can start only after
approval, a successful build, and distribution.
| <!--- | ||
| How to write block comments [you can do anything you want in here] | ||
| ---> | ||
|
|
||
| [comment]: # (How to write line comments [must not contain brackets]) | ||
|
|
||
| [comment]: # "How to write line comments [must not contain quotations]" | ||
|
|
||
| [//]: # (How to write line comments [must not contain brackets]) | ||
|
|
||
| [//]: # "How to write line comments [must not contain quotations]" | ||
|
|
||
| [comment]: <> (How to write line comments [must not contain brackets]) | ||
|
|
||
| [comment]: <> "How to write line comments [must not contain quotations]" | ||
|
|
||
| [//]: <> (How to write line comments [must not contain brackets]) | ||
|
|
||
| [//]: <> "How to write line comments [must not contain quotations]" |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the Markdown comment-syntax scratchpad from the guide.
Lines 1-19 are unrelated to the Demo Instance workflow. They also create unused or duplicate Markdown reference-definition warnings at Lines 5, 7, 13, and 15. Delete this block or move it to contributor documentation.
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 5-5: Link and image reference definitions should be needed
Unused link or image reference definition: "comment"
(MD053, link-image-reference-definitions)
[warning] 7-7: Link and image reference definitions should be needed
Duplicate link or image reference definition: "comment"
(MD053, link-image-reference-definitions)
[warning] 13-13: Link and image reference definitions should be needed
Duplicate link or image reference definition: "comment"
(MD053, link-image-reference-definitions)
[warning] 15-15: Link and image reference definitions should be needed
Duplicate link or image reference definition: "comment"
(MD053, link-image-reference-definitions)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/guide/user/demo.md` around lines 1 - 19, Remove the Markdown
comment-syntax scratchpad at the start of the guide, including the HTML comment
and all reference-definition examples, so the document begins with Demo Instance
workflow content; do not replace it with unrelated documentation.
Source: Linters/SAST tools
| ### 1. Create a Project in the Hub | ||
|
|
||
| To run an analysis, a project must first be created in the Hub. A project defines the scope of the analysis, | ||
| including the target nodes, the requested data, and the images to be used. Creating a project is described in detail [here](./project). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align the preparation step with project-proposal creation.
The sidebar labels /project as Submitting a Project Proposal, and src/guide/user/analysis.md requires a proposal before analysis creation. This step labels the same target Create a Project and does not state that prerequisite. Rename the step to match the linked workflow, or link to the actual project-creation page and explain when the proposal becomes available for analysis.
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 53-53: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/guide/user/demo.md` around lines 50 - 53, Update the preparation step
heading and description around the project workflow so they match the sidebar’s
“Submitting a Project Proposal” terminology and state that a proposal is
required before creating an analysis. Keep the link aligned with the documented
proposal-submission workflow, or explicitly explain when the project becomes
available for analysis.
| an analysis can be created within the project. Creating an analysis involves selecting the analysis code, the | ||
| target nodes, and the entrypoint for the analysis, and is described in detail [here](./analysis). | ||
|
|
||
| [//]: # (TODO: update analysis.md, its content is outdated) |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the stale TODO about analysis.md.
The TODO says analysis.md is outdated, but this PR updates src/guide/user/analysis.md. Remove the TODO or replace it with a current, actionable task.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/guide/user/demo.md` at line 81, Remove the stale TODO comment in the
documentation near the analysis.md reference, since src/guide/user/analysis.md
has been updated. Do not replace it unless there is a specific current,
actionable task to record.
1 participant
basiert auf PR #106
Summary by CodeRabbit