docs: add onboarding and thorough documentation for studio #4107
Conversation
WalkthroughSeveral new documentation files were added under the Studio section, providing an overview, installation instructions, architecture details, and a usage guide for AsyncAPI Studio. A metadata file was also introduced to organize the section within the documentation structure. No code or exported entities were altered. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant UI
participant EditorService
participant ParserService
participant NavigationService
participant MonacoEditor
participant AsyncAPIParser
participant ReactFlow
participant AsyncAPIReact
User->>UI: Interacts (edit, navigate, preview)
UI->>EditorService: Sends edit actions
EditorService->>MonacoEditor: Updates content
EditorService->>ParserService: Triggers validation/parsing
ParserService->>AsyncAPIParser: Parse & validate AsyncAPI document
ParserService-->>UI: Returns validation results
UI->>NavigationService: Updates navigation state
UI->>ReactFlow: Updates visual flow diagram
UI->>AsyncAPIReact: Updates documentation preview
Suggested labels
Suggested reviewers
Poem
Tip ⚡️ Faster reviews with caching
Enjoy the performance boost—your workflow just got faster. 📜 Recent review detailsConfiguration used: .coderabbit.yaml 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 180000ms (1)
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
TRohit20
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #4107 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 22 22
Lines 778 778
Branches 144 144
=========================================
Hits 778 778 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
markdown/docs/tools/studio/installation.md (1)
43-45: Specify language for the plain URL code block
For consistency, add a language identifier (e.g.,plaintext) to the code fence for the URL snippet:- ``` - http://localhost:3000 - ``` + ```plaintext + http://localhost:3000 + ```This enhances uniformity in code block rendering.
markdown/docs/tools/studio/usage.md (1)
75-75: Add missing period for consistency
The list item should end with a period:- 4. The preview updates automatically as you edit your document + 4. The preview updates automatically as you edit your document.🧰 Tools
🪛 LanguageTool
[uncategorized] ~75-~75: A period might be missing here.
Context: ... updates automatically as you edit your document ## Visualizing Your API To visualize ...(AI_EN_LECTOR_MISSING_PUNCTUATION_PERIOD)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
markdown/docs/tools/studio/_section.md(1 hunks)markdown/docs/tools/studio/architecture.md(1 hunks)markdown/docs/tools/studio/index.md(1 hunks)markdown/docs/tools/studio/installation.md(1 hunks)markdown/docs/tools/studio/usage.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tools/studio/usage.md
[uncategorized] ~75-~75: A period might be missing here.
Context: ... updates automatically as you edit your document ## Visualizing Your API To visualize ...
(AI_EN_LECTOR_MISSING_PUNCTUATION_PERIOD)
⏰ Context from checks skipped due to timeout of 180000ms (4)
- GitHub Check: Redirect rules - asyncapi-website
- GitHub Check: Header rules - asyncapi-website
- GitHub Check: Pages changed - asyncapi-website
- GitHub Check: Test NodeJS PR - macos-13
🔇 Additional comments (7)
markdown/docs/tools/studio/_section.md (1)
1-4: Correct front-matter for section metadata
Thetitleandweightvalues are properly configured to define and order the Studio section within the documentation.markdown/docs/tools/studio/installation.md (2)
1-4: Front-matter is correct
Thetitleandweightproperly classify this as the Installation Guide page within the Studio section.
100-112: Verify relative path to AsyncAPI CLI docs
The link../cli/should point to the correct CLI documentation in the MkDocs structure. Please confirm it resolves as expected.markdown/docs/tools/studio/index.md (1)
1-4: Front-matter is well-defined
Thetitleandweightaccurately place this introduction page at the start of the Studio section.markdown/docs/tools/studio/usage.md (1)
1-4: Front-matter is correctly configured
Thetitleandweightalign with its position in the Studio section (packed after Installation).markdown/docs/tools/studio/architecture.md (2)
1-4: Front-matter is accurate
Thetitleandweightcorrectly place this architecture overview as the last page in the Studio section.
8-34: Mermaid diagrams are properly fenced
All Mermaid diagrams in this document have matching opening and closing fences, ensuring they render correctly.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
markdown/docs/tools/studio/architecture.md (2)
1-4: Enhance frontmatter withdescriptionfield
Adding adescriptionkey in frontmatter improves SEO, consistency, and provides a summary for other tools (e.g., search indexing).Proposed diff:
--- a/markdown/docs/tools/studio/architecture.md +++ b/markdown/docs/tools/studio/architecture.md @@ --- title: 'Architecture' +description: >- + Detailed architectural overview of AsyncAPI Studio, including its layered + design, core services, components, data flow, and deployment options. weight: 50 ---
100-100: Clarify hierarchy of "State Management"
Since State Management is part of the Services Layer, consider demoting it to an####sub-heading or nesting it under the Services Layer section for clearer structure.-### State Management +#### State Management
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/tools/studio/architecture.md(1 hunks)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Test NodeJS PR - macos-13
|
Couple of things:
Tagging maintainers: @Amzani (Can add more if needed) |
|
@Shurtu-gal should I go ahead and implement those changes then ? But If we do that, usage doc gets much shorter and each document would be a separate document per use by itself. |
|
I suppose we can start with that, if the doc is too short we can merge them. |
|
@Shurtu-gal But my concern is, if we go with separate docs per use case, we will need to create a sub topic for usage and write the multiple docs under it, which would essentially overlap with guides purview? so how do you suggest we construct the IA in this case? Based on IA best practises and other tool documentation, we don’t usually add descriptive images and stuff, we keep it very simple and intuitive as it is as of now. Plus, I feel like we would be making it complex or divided at the moment, do we really wanna go there now? we can work towards the separation and to-do API tutorial iteratively going forward. WDYT @Amzani @AayushSaini101 |
|
@asyncapi/bounty_team |
|
Following up to see what @AayushSaini101 & @Amzani have to suggest to take it forward ACC. or review please ? |
What about splitting the docs itself in multiple section @TRohit20 ? |
|
|
|
we can but it would make it overlap and little complex maybe. but I am willing work with the suggestion, how do you suggest I break it up, I will have the changes pushed acc @AayushSaini101 |
@TRohit20 could you share structure how you are thinking to implement ? |
Description
The PR intends to introduce a set of documents for AsyncAPI Studio, aimed at enhancing user understanding and facilitating easier contributions.
The documentation covers multiple aspects such as installation, usage, and architecture.
Related issue(s)
Resolves the following bounty issue: asyncapi/studio#1169
Summary by CodeRabbit