From a8a6571195d2aaf3720268280f2aea8b164b38c5 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Mon, 21 Oct 2024 14:40:58 +0200 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Florence Njeri <40742916+Florence-Njeri@users.noreply.github.com> --- .changeset/hooks-in.md | 6 +++--- README.md | 12 ++++++------ apps/generator/docs/configuration-file.md | 2 +- apps/generator/docs/hooks.md | 6 +++--- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.changeset/hooks-in.md b/.changeset/hooks-in.md index d21fd9640..d3e5da350 100644 --- a/.changeset/hooks-in.md +++ b/.changeset/hooks-in.md @@ -2,6 +2,6 @@ "@asyncapi/generator": minor --- -- Package `@asyncapi/generator-hooks` is now part of `generator` repo and won't be released separately. Source code is stored under `apps/hooks` but the package/library name stays as it was originally for backward compatibility, -- By default `@asyncapi/generator-hooks` package, known as package with a lot of different hooks used in templates, is available in the generator and you no longer have to configure it in your `package.json` in `dependencies`. Package `@asyncapi/generator-hooks` will no longer be published to NPM separately and is deprecated. You can still have your own hooks, and you can still store them in a separate package and configure with your template, -- Remember that the fact that hooks package is now included by default, doesn't mean all hooks from it are enabled by default. You still have to enable given hook in the configuration explicitly because some hooks can execute automatically without passing a specific parameter. Also hook's supported parameters also need to be defined in your template's config. +- Package `@asyncapi/generator-hooks` is now part of `generator` repo and won't be released separately. Theource code is stored under `apps/hooks` but the `package/library` name stays as it was originally for backward compatibility, +- By default, the `@asyncapi/generator-hooks` package, known as **package** contains many different hooks used in templates and is available in the generator. You no longer have to configure it in your `package.json` in `dependencies`. The package, `@asyncapi/generator-hooks` will no longer be published to NPM separately and is deprecated. You can still have your own hooks, store them in a separate package, and configure them with your template. +- Remember that the fact that the hooks package is now included by default, doesn't mean all hooks from it are enabled by default. You still have to enable a given hook in the configuration file explicitly because some hooks can execute automatically without passing a specific parameter. Also, a hook's supported parameters need to be defined in your template's config. diff --git a/README.md b/README.md index edfad0ff7..3d09b55be 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ This is a Monorepo managed using [Turborepo](https://turbo.build/) and contains 1. [Generator](apps/generator): This is a tool that you can use to generate whatever you want basing on the AsyncAPI specification file as an input. -1. [Hooks](apps/hooks): This library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. Hooks are designed to let template developer to hook into the template generation process. Like for example one can create a hook code that will be automatically invoked right after the template generation process has ended. +1. [Hooks](apps/hooks): This library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. Hooks are designed to let template developers hook into the template generation process. For example, one can create a hook code that will be automatically invoked right after the template generation process has ended. -1. [Nunjucks-filters](apps/nunjucks-filters): This library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies seprately. +1. [Nunjucks-filters](apps/nunjucks-filters): This library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies separately. ![npm](https://img.shields.io/npm/v/@asyncapi/generator?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/generator?style=for-the-badge) @@ -57,7 +57,7 @@ You can find above templates and the ones provided by the community in **[this l ## Filters - `apps/nunjucks-filters` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies seprately. + `apps/nunjucks-filters` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. These filters are designed specifically for Nunjucks templates and are included by default with the generator, so there's no need to add them to dependencies separately. This library consists of: @@ -66,13 +66,13 @@ This library consists of: ## Hooks -`apps/hooks` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. [Hooks](https://www.asyncapi.com/docs/tools/generator/hooks) are functions called by the generator on a specific moment in the generation process. Hooks can be anonymous functions but you can also add function names. These hooks can have arguments provided to them or being expected to return a value. +The `apps/hooks` library contains generator filters that can be reused across multiple templates, helping to avoid redundant work. [Hooks](https://www.asyncapi.com/docs/tools/generator/hooks) are functions called by the generator at specific moments in the generation process. Hooks can be anonymous functions, but you can also assign them function names. These hooks can have arguments provided to them, or they may be expected to return a value. -These hooks are included in generator without adding any specific dependency to the library. You still have to enable given hook in the configuration explicitly because some hooks can execute automatically without passing a specific parameter. [Learn more about configuration and what hooks are available out of the box](https://www.asyncapi.com/docs/tools/generator/hooks#official-library). +These hooks are included in the generator without adding any specific dependency to the library. You still have to enable the given hook in the configuration explicitly because some hooks can execute automatically without passing a specific parameter. [Learn more about configuration and what hooks are available out of the box](https://www.asyncapi.com/docs/tools/generator/hooks#official-library). ## Contributing -For developement setup you can follow the detailed guide in [Developement guide](Development.md) +For the development setup, you can follow the detailed guide in [Developement guide](Development.md) Read [CONTRIBUTING](CONTRIBUTING.md) guide. diff --git a/apps/generator/docs/configuration-file.md b/apps/generator/docs/configuration-file.md index f30283c7c..dda21e983 100644 --- a/apps/generator/docs/configuration-file.md +++ b/apps/generator/docs/configuration-file.md @@ -20,7 +20,7 @@ The `generator` property from `package.json` file must contain a JSON object tha |`nonRenderableFiles`| [String] | A list of file paths or [globs](https://en.wikipedia.org/wiki/Glob_(programming)) that must be copied "as-is" to the target directory, i.e., without performing any rendering process. This is useful when you want to copy binary files. |`generator`| [String] | A string representing the generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning). |`filters`| [String] | A list of modules containing functions that can be used as Nunjucks filters. In case of external modules, remember they need to be added as a dependency in `package.json` of your template. -|`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 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 you must pass an array of strings. In 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. ### Example diff --git a/apps/generator/docs/hooks.md b/apps/generator/docs/hooks.md index 6e0aa7165..a864674bd 100644 --- a/apps/generator/docs/hooks.md +++ b/apps/generator/docs/hooks.md @@ -19,7 +19,7 @@ The following types of hooks are currently supported: The generator parses: - All the files in the `.hooks` directory inside the template. -- All modules listed in the template configuration and triggers only hooks that names were added to the config. You can use an [official hooks library](#official-library) that is bundled together with the generator. To learn how to add hooks to configuration [read more about the configuration file](configuration-file). +- All modules listed in the template configuration and triggers only hooks whose names were added to the config. You can use an [official hooks library](#official-library) that is bundled together with the generator. To learn how to add hooks to configuration [read more about the configuration file](configuration-file). ## Examples @@ -87,12 +87,12 @@ module.exports = { ## Official library -It is a library of reusable hooks that you can use in your templates. You only have to add it's name to configuration: `@asyncapi/generator-hooks` and specify which hook you want to enable. +It is a library of reusable hooks that you can use in your templates. You only have to add its name to the configuration: `@asyncapi/generator-hooks` and specify which hook you want to enable. This library consists of the following hooks: |Hook name|Hook type|Description| |---|---|---| -| `createAsyncapiFile` | `generate:after` | It creates AsyncAPI file with content of the spec file passed to the generator. By default it created the file in the root of the generation output directory. This hook also supports custom parameters that user can pass to template generation. Parameter called `asyncapiFileDir` allows user to specify the location where 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 | +| `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 | 1. In your template configuration in `package.json` specify you want to use this library and what hook exactly: ```json