docs(generator): update latest generator documentation #3602
Conversation
asyncapi-bot
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
|
Warning Rate limit exceeded@derberg has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 20 minutes and 15 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughThis pull request introduces comprehensive documentation updates for the AsyncAPI Generator, focusing on the deprecation of the Nunjucks render engine and the migration to the React render engine. The changes include adding deprecation notices to existing documentation, creating a new migration guide for transitioning from Nunjucks to React templates, and providing a detailed CLI migration guide to help users smoothly adopt the new AsyncAPI CLI and render engine. Changes
Possibly related PRs
Suggested reviewers
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
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
|
asyncapi-bot
requested review from
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
✅ Deploy Preview for asyncapi-website ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3602 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 732 732
=========================================
Hits 732 732 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
markdown/docs/tools/generator/migration-cli.md (1)
50-52: Add language specifiers to code blocks.The code blocks should specify their language for proper syntax highlighting.
Apply this diff:
-``` +```bash ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName-
+bash
asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookNameAlso applies to: 55-57
🧰 Tools
🪛 Markdownlint (0.37.0)
50-50: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
markdown/docs/tools/generator/migration-nunjucks-react.md (1)
36-36: Fix grammatical issues.Minor grammatical improvements needed:
Apply this diff:
-Below you can see some examples of filenames: +Below, you can see some examples of filenames: -introduced the React render engine from article +introduced the React render engine from the articleAlso applies to: 144-144
🧰 Tools
🪛 LanguageTool
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...omponent used inside the template file. Below you can see some examples of filenames:...(AI_HYDRA_LEO_MISSING_COMMA)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
markdown/docs/tools/generator/file-templates.md(1 hunks)markdown/docs/tools/generator/migration-cli.md(1 hunks)markdown/docs/tools/generator/migration-nunjucks-react.md(1 hunks)markdown/docs/tools/generator/nunjucks-render-engine.md(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.37.0)
markdown/docs/tools/generator/migration-cli.md
50-50: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 LanguageTool
markdown/docs/tools/generator/migration-nunjucks-react.md
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...omponent used inside the template file. Below you can see some examples of filenames:...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~144-~144: Possible missing article found.
Context: ...introduced the React render engine from article [React as a Generator Engine](https://w...
(AI_HYDRA_LEO_MISSING_THE)
⏰ Context from checks skipped due to timeout of 180000ms (2)
- GitHub Check: Automerge PR autoapproved by a bot
- GitHub Check: Lighthouse CI
🔇 Additional comments (4)
markdown/docs/tools/generator/migration-cli.md (1)
1-70: LGTM! Well-structured migration guide.The migration guide is comprehensive and well-organized, covering:
- Clear mapping of old to new CLI options
- Step-by-step migration instructions
- Verification steps
- Additional resources
🧰 Tools
🪛 Markdownlint (0.37.0)
50-50: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
55-55: null
Fenced code blocks should have a language specified(MD040, fenced-code-language)
markdown/docs/tools/generator/nunjucks-render-engine.md (1)
6-6: LGTM! Clear deprecation notice.The deprecation notice is well-placed at the beginning of the document and provides a clear directive to use the React renderer engine instead, with a link to more details.
markdown/docs/tools/generator/migration-nunjucks-react.md (1)
1-144: LGTM! Excellent migration guide.The migration guide is thorough and well-structured, covering:
- Step-by-step migration process
- Clear examples comparing Nunjucks and React implementations
- Testing recommendations
- Additional resources
🧰 Tools
🪛 LanguageTool
[uncategorized] ~36-~36: Possible missing comma found.
Context: ...omponent used inside the template file. Below you can see some examples of filenames:...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~144-~144: Possible missing article found.
Context: ...introduced the React render engine from article [React as a Generator Engine](https://w...(AI_HYDRA_LEO_MISSING_THE)
markdown/docs/tools/generator/file-templates.md (1)
10-10: LGTM! Clear deprecation notice.The deprecation notice is well-placed and consistent with the notice in other files, providing a clear directive to use the React renderer engine instead.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
markdown/docs/tools/generator/migration-cli.md (2)
12-14: Add example for complex disable-hook option.Consider adding a concrete example for the
--disable-hookoption to demonstrate its usage, as it's one of the more complex options with multiple parameters.- **-d, --disable-hook [hooks...]** - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --disable-hook <hookType>=<hookName>` + - **Example:** `asyncapi generate fromTemplate api.yaml @asyncapi/html-template --disable-hook generate=createDirectories`
65-70: Consider adding a troubleshooting section.The resources section is helpful, but consider adding a "Common Issues" or "Troubleshooting" section to address frequently encountered migration challenges.
## Additional Resources **CLI Documentation**: [AsyncAPI CLI Documentation](https://www.asyncapi.com/docs/tools/cli) **Installation**: [AsyncAPI CLI Installation](https://www.asyncapi.com/docs/tools/cli/installation) **Usage**: [AsyncAPI CLI Usage](https://www.asyncapi.com/docs/tools/cli/usage) **Support**: For any issues with CLI, create an issue in [CLI repository](https://github.com/asyncapi/cli). + +## Common Issues + +- **Error: Template not found**: Ensure you're using the correct template name and it's installed properly +- **Migration validation**: Use `--debug` flag to verify the command translation +- **Template compatibility**: Check template compatibility with the new CLI version
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/tools/generator/migration-cli.md(1 hunks)
🧰 Additional context used
🪛 Markdownlint (0.37.0)
markdown/docs/tools/generator/migration-cli.md
50-50: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 180000ms (1)
- GitHub Check: Lighthouse CI
🔇 Additional comments (1)
markdown/docs/tools/generator/migration-cli.md (1)
1-7: LGTM! Clear and concise introduction.The frontmatter is properly formatted and the introduction clearly states the purpose of the guide.
| **Using `ag`**: | ||
| ``` | ||
| ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName | ||
| ``` | ||
|
|
||
| **Using AsyncAPI CLI**: | ||
| ``` | ||
| asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add language specifiers to code blocks.
Add language specifiers to the fenced code blocks for proper syntax highlighting:
-```
+```bash
ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName- +bash
asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
🧰 Tools
🪛 Markdownlint (0.37.0)
50-50: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
55-55: null
Fenced code blocks should have a language specified
(MD040, fenced-code-language)
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3602--asyncapi-website.netlify.app/ |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3602--asyncapi-website.netlify.app/ |
derberg
deleted the
update-generator-docs-fd5dfd7687c0e4899a548718bf420226a5cd60f9
branch
Updated generator documentation is available and this PR introduces update to generator folder on the website
Summary by CodeRabbit
agCLI to AsyncAPI CLI