docs(cli): update latest cli documentation #3606
Conversation
asyncapi-bot
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
WalkthroughThis pull request introduces a new documentation file Changes
Possibly related PRs
Suggested labels
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
|
✅ 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 #3606 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 20 20
Lines 732 732
=========================================
Hits 732 732 ☔ View full report in Codecov by Sentry. |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3606--asyncapi-website.netlify.app/ |
asyncapi-bot
deleted the
update-cli-docs-b2711afb50625c54786906aaf5f07aa0c271cb2b
branch
![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 (5)
markdown/docs/tools/cli/github-action.md (5)
21-21: Fix duplicate phrase in command description.Remove the redundant "Available commands" phrase for better readability.
-Command that you wish to run. You can find all available commands Available commands are: +Command that you wish to run. Available commands are:🧰 Tools
🪛 LanguageTool
[grammar] ~21-~21: This phrase is duplicated. You should probably use “available commands” only once.
Context: ... that you wish to run. You can find all available commands Available commands are: -generate- generates documenta...(PHRASE_REPETITION)
62-62: Format URL as proper markdown link.Convert the bare URL to a proper markdown link for better documentation standards.
-Template for the generator. Official templates are listed here https://github.com/asyncapi/generator#list-of-official-generator-templates. You can pass template as npm package, url to git repository, link to tar file or local template. +Template for the generator. Official templates are listed [here](https://github.com/asyncapi/generator#list-of-official-generator-templates). You can pass template as npm package, url to git repository, link to tar file or local template.🧰 Tools
🪛 Markdownlint (0.37.0)
62-62: null
Bare URL used(MD034, no-bare-urls)
129-129: Improve grammar in workflow descriptions.The phrase "could look like" is grammatically incorrect in these contexts.
-In case you want to validate your asyncapi file first, and also send generated HTML to GitHub Pages this is how full workflow could look like: +In case you want to validate your asyncapi file first, and also send generated HTML to GitHub Pages, here's an example workflow: -In case you want to use models generated from your AsyncAPI document, you can use this action to generate them and then use them in your workflow. This is how full workflow could look like: +In case you want to use models generated from your AsyncAPI document, you can use this action to generate them and then use them in your workflow. Here's an example workflow: -In case you want to validate your AsyncAPI document changes, you can use this action to validate them and then use them in your workflow. This is how full workflow could look like: +In case you want to validate your AsyncAPI document changes, you can use this action to validate them and then use them in your workflow. Here's an example workflow:Also applies to: 166-166, 195-195
🧰 Tools
🪛 LanguageTool
[grammar] ~129-~129: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ... generated HTML to GitHub Pages this is how full workflow could look like: ```yaml name: AsyncAPI documents proc...(HOW_IT_SHOULD_BE)
221-236: Enhance local testing instructions.
- Fix grammar by adding missing article
- Add information about prerequisites for local testing
-Use following commands to run and test github action locally: +Use the following commands to run and test the GitHub Action locally: +### Prerequisites +- Docker installed and running +- Node.js and npm installed + 1. Build docker image of github action for cli🧰 Tools
🪛 LanguageTool
[uncategorized] ~221-~221: Possible missing article found.
Context: ...asyncapi.yml ``` ## Local dry run Use following commands to run and test github action ...(AI_HYDRA_LEO_MISSING_THE)
237-239: Enhance troubleshooting section.
- Fix grammar
- Add more common troubleshooting scenarios
## Troubleshooting -You can enable more log information in GitHub Action by adding `ACTIONS_STEP_DEBUG` secret to repository where you want to use this action. Set the value of this secret to `true` and you'll notice more debug logs from this action. +You can enable more log information in GitHub Actions by adding the `ACTIONS_STEP_DEBUG` secret to the repository where you want to use this action. Set the value of this secret to `true` and you'll notice more debug logs from this action. + +### Common Issues + +1. **Template Not Found** + - Verify the template name and version + - Ensure npm registry is accessible + +2. **Permission Issues** + - Check if `GITHUB_TOKEN` has required permissions + - Verify repository access settings + +3. **Invalid AsyncAPI Document** + - Validate your AsyncAPI document using the online validator + - Check for syntax errors in YAML/JSON🧰 Tools
🪛 LanguageTool
[uncategorized] ~239-~239: Possible missing article found.
Context: ...y addingACTIONS_STEP_DEBUGsecret to repository where you want to use this action. Set ...(AI_HYDRA_LEO_MISSING_THE)
📜 Review details
Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
markdown/docs/tools/cli/github-action.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tools/cli/github-action.md
[uncategorized] ~17-~17: Possible missing comma found.
Context: ...nd to default to latest version. This way there is no overhead with the script up...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~17-~17: The verb ‘recommend’ is used with the gerund form.
Context: ...t of time to update the CLI version, we recommend to update it only when you need to use another on...
(ADMIT_ENJOY_VB)
[grammar] ~21-~21: This phrase is duplicated. You should probably use “available commands” only once.
Context: ... that you wish to run. You can find all available commands Available commands are: - generate - generates documenta...
(PHRASE_REPETITION)
[style] ~32-~32: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... issues later on. > For example, if you want to run `asyncapi bundle ./asyncapi.yaml --...
(REP_WANT_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...put. ### custom_command In case you want to use custom command you need to pass t...
(REP_WANT_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...se you want to use custom command you need to pass the command that you want to run i...
(REP_NEED_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...d you need to pass the command that you want to run in this input. You can find all ava...
(REP_WANT_TO_VB)
[style] ~67-~67: Consider using “incompatible” to avoid wordiness.
Context: ...case of release of the template that is not compatible with given version of the generator. #...
(NOT_ABLE_PREMIUM)
[style] ~81-~81: To form a complete sentence, be sure to include a subject.
Context: ...output Path to the output directory. Can be used for generate and convert co...
(MISSING_IT_THERE)
[uncategorized] ~99-~99: Possible missing comma found.
Context: ...every time. It will pull it from Docker Hub as it is already built there. ### Basi...
(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~124-~124: Using many exclamation marks might seem excessive (in this case: 8 exclamation marks for a text that’s 5740 characters long)
Context: ...ent/ sidebarOrganization=byTags" ``` > [!IMPORTANT] > Note the usage of -p in `...
(EN_EXCESSIVE_EXCLAMATION)
[grammar] ~129-~129: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ... generated HTML to GitHub Pages this is how full workflow could look like: ```yaml name: AsyncAPI documents proc...
(HOW_IT_SHOULD_BE)
[style] ~166-~166: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...flow for generating models In case you want to use models generated from your AsyncAPI...
(REP_WANT_TO_VB)
[grammar] ~166-~166: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ...then use them in your workflow. This is how full workflow could look like: ```yaml name: AsyncAPI documents pro...
(HOW_IT_SHOULD_BE)
[style] ~195-~195: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... AsyncAPI document changes In case you want to validate your AsyncAPI document changes...
(REP_WANT_TO_VB)
[grammar] ~195-~195: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ...then use them in your workflow. This is how full workflow could look like: ```yaml name: Validate AsyncAPI docum...
(HOW_IT_SHOULD_BE)
[uncategorized] ~221-~221: Possible missing article found.
Context: ...asyncapi.yml ``` ## Local dry run Use following commands to run and test github action ...
(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~239-~239: Possible missing article found.
Context: ...y adding ACTIONS_STEP_DEBUG secret to repository where you want to use this action. Set ...
(AI_HYDRA_LEO_MISSING_THE)
🪛 Markdownlint (0.37.0)
markdown/docs/tools/cli/github-action.md
62-62: null
Bare URL used
(MD034, no-bare-urls)
32-32: null
Spaces inside code span elements
(MD038, no-space-in-code)
⏰ Context from checks skipped due to timeout of 180000ms (2)
- GitHub Check: Automerge PR autoapproved by a bot
- GitHub Check: Lighthouse CI
🔇 Additional comments (2)
markdown/docs/tools/cli/github-action.md (2)
1-7: LGTM! Clear and informative introduction.The introduction effectively explains the purpose and capabilities of the GitHub Action while providing relevant links to source repositories.
1-239: Well-structured and comprehensive documentation!The documentation effectively covers all aspects of the AsyncAPI CLI GitHub Action, including setup, usage examples, and troubleshooting. While there are some minor grammatical and formatting improvements suggested above, the overall quality and completeness of the documentation is excellent.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~17-~17: Possible missing comma found.
Context: ...nd to default tolatestversion. This way there is no overhead with the script up...(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~17-~17: The verb ‘recommend’ is used with the gerund form.
Context: ...t of time to update the CLI version, we recommend to update it only when you need to use another on...(ADMIT_ENJOY_VB)
[grammar] ~21-~21: This phrase is duplicated. You should probably use “available commands” only once.
Context: ... that you wish to run. You can find all available commands Available commands are: -generate- generates documenta...(PHRASE_REPETITION)
[style] ~32-~32: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... issues later on. > For example, if you want to run `asyncapi bundle ./asyncapi.yaml --...(REP_WANT_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...put. ###custom_commandIn case you want to usecustomcommand you need to pass t...(REP_WANT_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...se you want to usecustomcommand you need to pass the command that you want to run i...(REP_NEED_TO_VB)
[style] ~36-~36: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...d you need to pass the command that you want to run in this input. You can find all ava...(REP_WANT_TO_VB)
[style] ~67-~67: Consider using “incompatible” to avoid wordiness.
Context: ...case of release of the template that is not compatible with given version of the generator. #...(NOT_ABLE_PREMIUM)
[style] ~81-~81: To form a complete sentence, be sure to include a subject.
Context: ...outputPath to the output directory. Can be used forgenerateandconvertco...(MISSING_IT_THERE)
[uncategorized] ~99-~99: Possible missing comma found.
Context: ...every time. It will pull it from Docker Hub as it is already built there. ### Basi...(AI_HYDRA_LEO_MISSING_COMMA)
[style] ~124-~124: Using many exclamation marks might seem excessive (in this case: 8 exclamation marks for a text that’s 5740 characters long)
Context: ...ent/ sidebarOrganization=byTags" ``` > [!IMPORTANT] > Note the usage of-pin `...(EN_EXCESSIVE_EXCLAMATION)
[grammar] ~129-~129: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ... generated HTML to GitHub Pages this is how full workflow could look like: ```yaml name: AsyncAPI documents proc...(HOW_IT_SHOULD_BE)
[style] ~166-~166: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...flow for generating models In case you want to use models generated from your AsyncAPI...(REP_WANT_TO_VB)
[grammar] ~166-~166: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ...then use them in your workflow. This is how full workflow could look like: ```yaml name: AsyncAPI documents pro...(HOW_IT_SHOULD_BE)
[style] ~195-~195: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... AsyncAPI document changes In case you want to validate your AsyncAPI document changes...(REP_WANT_TO_VB)
[grammar] ~195-~195: ‘Like’ cannot be used with the question word ‘how’ in this context.
Context: ...then use them in your workflow. This is how full workflow could look like: ```yaml name: Validate AsyncAPI docum...(HOW_IT_SHOULD_BE)
[uncategorized] ~221-~221: Possible missing article found.
Context: ...asyncapi.yml ``` ## Local dry run Use following commands to run and test github action ...(AI_HYDRA_LEO_MISSING_THE)
[uncategorized] ~239-~239: Possible missing article found.
Context: ...y addingACTIONS_STEP_DEBUGsecret to repository where you want to use this action. Set ...(AI_HYDRA_LEO_MISSING_THE)
🪛 Markdownlint (0.37.0)
62-62: null
Bare URL used(MD034, no-bare-urls)
32-32: null
Spaces inside code span elements(MD038, no-space-in-code)
Updated cli documentation is available and this PR introduces update to cli folder on the website
Summary by CodeRabbit