docs(generator): update latest generator documentation #3349
Conversation
asyncapi-bot
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
WalkthroughThe pull request includes updates to the documentation for the Changes
Possibly related PRs
Suggested reviewers
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
CodeRabbit Configuration File (
|
asyncapi-bot
requested review from
devilkiller-ag,
sambhavgupta0705,
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 #3349 +/- ##
=======================================
Coverage 49.14% 49.14%
=======================================
Files 21 21
Lines 647 647
=======================================
Hits 318 318
Misses 329 329 ☔ View full report in Codecov by Sentry. |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3349--asyncapi-website.netlify.app/ |
![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
🧹 Outside diff range and nitpick comments (6)
markdown/docs/tools/generator/hooks.md (5)
Line range hint 8-17: Fix table formatting for better maintainability.
The table content is well-structured, but there are some formatting inconsistencies.
Apply these changes to follow Markdown best practices:
-|Hook type|Description| Return type | Arguments
-|---|---|---|---|
+| Hook type | Description | Return type | Arguments |
+| --- | --- | --- | --- |🧰 Tools
🪛 LanguageTool
[uncategorized] ~6-~6: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...rocess. Hooks can be anonymous functions but you can also add function names. These ...
(COMMA_COMPOUND_SENTENCE)
18-23: Fix grammar in the location section.
The content is clear, but there's a minor grammatical issue.
Apply this change:
-All modules listed in the template configuration and triggers only hooks whose names were added to the config.
+All modules listed in the template configuration, triggering only hooks whose names were added to the config.Line range hint 24-86: Examples are well-structured and informative.
The examples effectively demonstrate various hook implementations. Consider adding TypeScript type annotations in the examples for better type safety and documentation.
Example with TypeScript:
import { Generator } from '@asyncapi/generator';
interface FileTemplateHookArguments {
originalFilename: string;
}
module.exports = {
'setFileTemplateName': (generator: Generator, hookArguments: FileTemplateHookArguments): string => {
const currentFilename = hookArguments.originalFilename;
return currentFilename.replace('-', '_');
}
};🧰 Tools
🪛 LanguageTool
[formatting] ~26-~26: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...efault location or in a separate library, because such hooks need to be explicitly config...
(COMMA_BEFORE_BECAUSE)
🪛 Markdownlint
16-16: null
Spaces inside code span elements
(MD038, no-space-in-code)
88-118: Improve table formatting and spacing in the Official library section.
The content is excellent, but there are some formatting improvements needed.
- Add blank lines around the table
- Fix table formatting:
-|Hook name|Hook type|Description|
-|---|---|---|
+
+| Hook name | Hook type | Description |
+| --- | --- | --- |
+🧰 Tools
🪛 Markdownlint
93-93: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
94-94: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
95-95: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
93-93: null
Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
7-7: Consider adding version compatibility information.
To help users understand compatibility requirements, consider adding a section about:
- Minimum generator version required
- Node.js version compatibility
- Any breaking changes in hook behavior across versions
Would you like me to help draft this section?
markdown/docs/tools/generator/configuration-file.md (1)
23-23: Fix table formatting and improve readability.
The updated hooks documentation is comprehensive and well-structured. However, there are a few minor improvements needed:
- Add a trailing pipe to maintain consistent table formatting
- Add a comma after "For each module" to improve readability
Apply this diff:
-|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name.
+|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module, you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name. |🧰 Tools
🪛 LanguageTool
[typographical] ~23-~23: It appears that a comma is missing.
Context: ...plate in the default location. For each module you must specify the exact name of the ...
(DURING_THAT_TIME_COMMA)
🪛 Markdownlint
23-23: Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
Table pipe style
(MD055, table-pipe-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
- markdown/docs/tools/generator/configuration-file.md (2 hunks)
- markdown/docs/tools/generator/hooks.md (3 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tools/generator/configuration-file.md
[typographical] ~23-~23: It appears that a comma is missing.
Context: ...plate in the default location. For each module you must specify the exact name of the ...
(DURING_THAT_TIME_COMMA)
markdown/docs/tools/generator/hooks.md
[formatting] ~26-~26: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...efault location or in a separate library, because such hooks need to be explicitly config...
(COMMA_BEFORE_BECAUSE)
🪛 Markdownlint
markdown/docs/tools/generator/configuration-file.md
23-23: Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
Table pipe style
(MD055, table-pipe-style)
markdown/docs/tools/generator/hooks.md
93-93: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
94-94: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
95-95: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
93-93: null
Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (1)
markdown/docs/tools/generator/configuration-file.md (1)
67-68: LGTM! Clear and helpful examples.
The examples effectively demonstrate both single hook usage with @asyncapi/generator-hooks and multiple hooks usage with a custom package.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (5)
markdown/docs/tools/generator/hooks.md (4)
Line range hint 8-17: Enhance table formatting for better readability.
The Types section is a valuable addition. Consider these improvements for consistency:
- Use consistent formatting for return types (e.g., "void" vs "string")
- Add specific parameter types in the Arguments column
|Hook type|Description| Return type | Arguments|
|---|---|---|---|
-| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](/api)
-| `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](/api)
-| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates.md). | string : a new filename for the generator to use for the file template. | [The generator instance](/api) and object in the form of `{ "originalFilename" : string }`
+| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | `void` | `generator: Generator` |
+| `generate:after` | Called at the very end of the generation. | `void` | `generator: Generator` |
+| `setFileTemplateName` | Called right before saving a new file generated by [file template](./file-templates.md). | `string` | `generator: Generator, args: { originalFilename: string }` |🧰 Tools
🪛 LanguageTool
[uncategorized] ~6-~6: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...rocess. Hooks can be anonymous functions but you can also add function names. These ...
(COMMA_COMPOUND_SENTENCE)
Line range hint 24-86: Consider enhancing the code examples with best practices.
While the examples are clear and informative, consider these improvements:
- Add error handling in the file writing operation
- Add type checking for the AsyncAPI instance
- Include JSDoc comments for better documentation
Example enhancement for the AsyncAPI file creation:
module.exports = {
- 'generate:after': generator => {
+ 'generate:after': async generator => {
+ try {
const asyncapi = generator.originalAsyncAPI;
let extension;
try {
JSON.parse(asyncapi);
extension = 'json';
} catch (e) {
extension = 'yaml';
}
- fs.writeFileSync(path.resolve(generator.targetDir, `asyncapi.${extension}`), asyncapi);
+ await fs.promises.writeFile(
+ path.resolve(generator.targetDir, `asyncapi.${extension}`),
+ asyncapi
+ );
+ } catch (error) {
+ console.error('Failed to create AsyncAPI file:', error);
+ throw error;
+ }
}
};🧰 Tools
🪛 LanguageTool
[formatting] ~26-~26: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...efault location or in a separate library, because such hooks need to be explicitly config...
(COMMA_BEFORE_BECAUSE)
🪛 Markdownlint
16-16: null
Spaces inside code span elements
(MD038, no-space-in-code)
88-118: Enhance the official library documentation.
The section provides valuable information about the official hooks library. Consider these improvements:
- Fix table formatting (remove trailing pipes)
- Add version information for the @asyncapi/generator-hooks package
- Include a link to the package's repository
-|Hook name|Hook type|Description|
-|---|---|---|
-| `createAsyncapiFile` | `generate:after` | It creates an AsyncAPI file with the content of the spec file passed to the generator. By default, it creates the file in the root of the generation output directory. This hook also supports custom parameters that the user can pass to template generation. The parameter called `asyncapiFileDir` allows the user to specify the location where the spec file should be created. To make your template users use this parameter, you need to add it to the configuration of your template like other parameters |
+Hook name|Hook type|Description
+---|---|---
+`createAsyncapiFile` | `generate:after` | Creates an AsyncAPI file with the content of the spec file passed to the generator. By default, creates the file in the root of the generation output directory. Supports the `asyncapiFileDir` parameter to specify a custom file location.Also, consider adding installation instructions:
Install the official hooks library:
```bash
npm install @asyncapi/generator-hooks
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 LanguageTool</summary>
[uncategorized] ~107-~107: Possible missing article found.
Context: ...me hooks support custom parameters that template's user can use to specify different beh...
(AI_HYDRA_LEO_MISSING_THE)
</details>
<details>
<summary>🪛 Markdownlint</summary>
93-93: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
---
94-94: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
---
95-95: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
---
93-93: null
Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
</details>
</details>
---
`107-107`: **Fix grammar in the documentation.**
Add the missing article "the" before "template's user":
```diff
-Some hooks support custom parameters that template's user can use
+Some hooks support custom parameters that the template's user can use
🧰 Tools
🪛 LanguageTool
[uncategorized] ~107-~107: Possible missing article found.
Context: ...me hooks support custom parameters that template's user can use to specify different beh...
(AI_HYDRA_LEO_MISSING_THE)
markdown/docs/tools/generator/configuration-file.md (1)
23-23: Add comma for better readability.
The description is comprehensive and well-structured. However, there's a minor grammatical improvement needed.
Apply this change:
-|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name.
+|`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in the default location. For each module, you must specify the exact name of the hook that should be used in the template. For a single hook, you can specify it as a string; for more hooks, you must pass an array of strings. In the case of external modules, remember they need to be added as a dependency in `package.json` of your template. There is also [an official hooks library](hooks#official-library) always included in the generator. As this is a library of multiple hooks, you still need to explicitly specify in the configuration which one you want to use. Use `@asyncapi/generator-hooks` as the library name.🧰 Tools
🪛 LanguageTool
[typographical] ~23-~23: It appears that a comma is missing.
Context: ...plate in the default location. For each module you must specify the exact name of the ...
(DURING_THAT_TIME_COMMA)
🪛 Markdownlint
23-23: Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
Table pipe style
(MD055, table-pipe-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
- markdown/docs/tools/generator/configuration-file.md (2 hunks)
- markdown/docs/tools/generator/hooks.md (3 hunks)
🧰 Additional context used
🪛 LanguageTool
markdown/docs/tools/generator/configuration-file.md
[typographical] ~23-~23: It appears that a comma is missing.
Context: ...plate in the default location. For each module you must specify the exact name of the ...
(DURING_THAT_TIME_COMMA)
markdown/docs/tools/generator/hooks.md
[formatting] ~26-~26: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...efault location or in a separate library, because such hooks need to be explicitly config...
(COMMA_BEFORE_BECAUSE)
[uncategorized] ~107-~107: Possible missing article found.
Context: ...me hooks support custom parameters that template's user can use to specify different beh...
(AI_HYDRA_LEO_MISSING_THE)
🪛 Markdownlint
markdown/docs/tools/generator/configuration-file.md
23-23: Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
Table pipe style
(MD055, table-pipe-style)
markdown/docs/tools/generator/hooks.md
93-93: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
94-94: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
95-95: Expected: leading_only; Actual: leading_and_trailing; Unexpected trailing pipe
Table pipe style
(MD055, table-pipe-style)
93-93: null
Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🔇 Additional comments (2)
markdown/docs/tools/generator/hooks.md (1)
18-23: LGTM!
The Location section clearly explains hook locations and properly references related documentation sections.
markdown/docs/tools/generator/configuration-file.md (1)
67-68: LGTM! Clear and instructive example.
The example effectively demonstrates both single hook usage with the official library and multiple hooks configuration with a custom package.
|
/rtm |
asyncapi-bot
deleted the
update-generator-docs-2d16234f26e6af4307ece99d8d7ccf9cc97ee5de
branch
Updated generator documentation is available and this PR introduces update to generator folder on the website
Summary by CodeRabbit
generatorproperty documentation inpackage.jsonto clarifyhooksconfiguration, including details about an official hooks library.hooks.mddocument with new sections on hook types and an official hooks library, improving clarity and usability for users.