docs(generator): update latest generator documentation (#3350)

markdown/docs/tools/generator/api.md

@@ -13,6 +13,7 @@ Reference API documentation for AsyncAPI Generator library.
 * [Generator](#Generator)
     * [new Generator(templateName, targetDir, options)](#new_Generator_new)
     * _instance_
+        * [.compile](#Generator+compile) : `Boolean`
         * [.registry](#Generator+registry) : `Object`
         * [.templateName](#Generator+templateName) : `String`
         * [.targetDir](#Generator+targetDir) : `String`
@@ -64,6 +65,7 @@ Instantiates a new Generator object.
     - [.forceWrite] `Boolean` ` = false` - Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
     - [.install] `Boolean` ` = false` - Install the template and its dependencies, even when the template has already been installed.
     - [.debug] `Boolean` ` = false` - Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
+    - [.compile] `Boolean` ` = true` - Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder
     - [.mapBaseUrlToFolder] `Object.<String, String>` - Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/  folder=./test/docs/ .
     - [.registry] `Object` - Optional parameter with private registry configuration
         - [.url] `String` - Parameter to pass npm registry url
@@ -85,6 +87,13 @@ const generator = new Generator('@asyncapi/html-template', path.resolve(__dirnam
 });
 ```
 
+<a name="Generator+compile"></a>
+
+* generator.compile : `Boolean`** :
+Whether to compile the template or use the cached transpiled version provided by template in '__transpiled' folder.
+
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+registry"></a>
 
 * generator.registry : `Object`** :

markdown/docs/tools/generator/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.
+|`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
 
@@ -64,7 +64,8 @@ The `generator` property from `package.json` file must contain a JSON object tha
     "my-package-with-filters"
   ],
   "hooks": {
-    "@asyncapi/generator-hooks": "hookFunctionName"
+    "@asyncapi/generator-hooks": "hookFunctionName",
+    "my-custom-hooks-package": ["myHook", "andAnotherOne"]
   }
 }
 ```

markdown/docs/tools/generator/hooks.md

@@ -4,6 +4,9 @@ weight: 130
 ---
 
 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.
+
+## Types
+
 The following types of hooks are currently supported:
 
 |Hook type|Description| Return type | Arguments 
@@ -12,13 +15,15 @@ The following types of hooks are currently supported:
 | `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 }`
 
+## Location
+
 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 the official AsyncAPI [hooks library](https://github.com/asyncapi/generator-hooks). To learn how to add hooks to configuration [read more about the configuration file](https://www.asyncapi.com/docs/tools/generator/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
+## Examples
 
-> Some of the examples have names of hook functions provided and some not. Keep in mind that hook functions kept in template in default location do not require a name. Name is required only if you keep hooks in non default location or in a separate library, because such hooks need to be explicitly configured in the configuration file. For more details on hooks configuration [read more about the configuration file](https://www.asyncapi.com/docs/tools/generator/configuration-file).
+> Some of the examples have names of hook functions provided and some not. Keep in mind that hook functions kept in template in default location do not require a name. Name is required only if you keep hooks in non default location or in a separate library, because such hooks need to be explicitly configured in the configuration file. For more details on hooks configuration [read more about the configuration file](configuration-file).
 
 Most basic modules with hooks look like this:
 ```js
@@ -79,3 +84,35 @@ module.exports = {
 	};
 };
 ```
+
+## Official library
+
+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 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
+    {
+      "generator": {
+          "hooks": {
+              "@asyncapi/generator-hooks": "createAsyncapiFile"
+          }
+      }
+    }
+    ```
+1. Some hooks support custom parameters that template's user can use to specify different behaviour of the hook. To enable these, you need to also add them to the list of your template's parameters:
+    ```json
+    {
+      "generator": {
+          "parameters": {
+            "asyncapiFileDir": {
+                "description": "This template by default also outputs the AsyncAPI document that was passed as input. You can specify with this parameter what should be the location of this AsyncAPI document, relative to specified template output."
+            }
+        }
+      }
+    }
+    ```