docs: create the model generation guide (#1096)

.github/workflows/update-docs-in-website.yml

@@ -35,6 +35,7 @@ jobs:
       - name: Copy generator folder from Current Repo to Another
         working-directory: ./website
         run: |
+          rm -r ./pages/docs/tools/generator
           mkdir -p ./pages/docs/tools/generator
           rm ../generator/docs/README.md
           rm -r ../generator/docs/jsdoc2md-handlebars

docs/index.md

@@ -5,6 +5,9 @@ weight: 10
 
 The AsyncAPI generator is a tool that generates anything you want using the **[AsyncAPI Document](generator/asyncapi-document)** and **[Template](generator/template)** that are supplied as inputs to the AsyncAPI CLI. The generator was built with extensibility in mind; you can use the generator to generate anything you want, provided that it can be defined in a template, such as code, diagrams, markdown files, microservices, and applications. A number of [community-maintained templates](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) are now available for immediate usage.
 
+> **Note:**
+> If your primary objective is to generate models/classes for your event-driven architecture apps, use [AsyncAPI Modelina](/docs/tools/generator/model-generation), which is supported in the AsyncAPI CLI, instead of using the AsyncAPI Generator. Modelina is specifically designed for model generation and provides utilities for working with the AsyncAPI document.
+
 ### Generator use cases 
 - Generation of interactive and understandable API documentation
 - Generation of APIs' client libraries

docs/installation-guide.md

@@ -53,7 +53,7 @@ You can install in Linux by using `dpkg`, a package manager for debian:
 For further installation instructions for different operating systems, read the [AsyncAPI CLI documentation](https://github.com/asyncapi/cli#installation).
 
 > **Remember:** 
-> Each [community-developed template](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) is dependent on a certain version of the generator for it to work correctly. Before you install the generator CLI, check the template's `package.json` for the version of the generator CLI your template is compatible with. Read the [versioning docs](versioning) to learn why it's important to use certain generator versions with your templates.
+> Each [community-developed template](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) is dependent on a certain version of the generator for it to work correctly. Before you install the AsyncAPI CLI, check the template's `package.json` for the version of the AsyncAPI CLI your template is compatible with. Read the [versioning docs](versioning) to learn why it's important to use certain generator versions with your templates.
 
 ### Update AsyncAPI CLI
 There are several reasons why you might want to update your generator version:

docs/model-generation.md

@@ -0,0 +1,84 @@
+---
+title: "Adding models generation in template"
+weight: 200
+---
+
+This guide will walk you through the process of enabling models/types generation in a template by using [Modelina](https://www.asyncapi.com/tools/modelina).
+
+Modelina is an AsyncAPI library designed for generating data models using inputs such as [AsyncAPI](generator/asyncapi-document), OpenAPI, or JSON schema inputs. Its functionality revolves around creating data models from the provided AsyncAPI document and the model template, which defines message payloads. It is better to use Modelina in your template to handle model generation rather than providing custom templates.
+
+You can integrate the work shown in this guide into a template by following the [tutorial about creating a template](https://www.asyncapi.com/docs/tools/generator/generator-template).
+
+In this guide, you'll learn how to use Modelina in a template code to enable support for Python data model generation.
+
+## Add Modelina dependency
+
+Install Modelina in your project using npm: `npm install --save @asyncapi/modelina`.
+
+Ensure your template's `package.json` file now contains Modelina pointing to its latest version:
+
+ ```json
+ "dependencies": {
+    // ...
+    "@asyncapi/modelina": "^2.0.5"
+    // ...
+  }
+```
+
+## Create a models.js file
+
+Create a new directory in the **template** directory named **src/models** and create a **models.js** file within it. In the **models.js** file, add the following code:
+
+```python
+// 1
+import { File } from '@asyncapi/generator-react-sdk';
+// 2
+import { PythonGenerator, FormatHelpers } from '@asyncapi/modelina';
+
+/**
+ * @typedef RenderArgument
+ * @type {object}
+ * @property {AsyncAPIDocument} asyncapi document object received from the generator.
+ */
+
+/**
+ * Render all schema models
+ * @param {RenderArgument} param0 
+ * @returns 
+ */
+// 3
+export default async function schemaRender({ asyncapi }) {
+  // 4 
+  const pythonGenerator = new PythonGenerator();
+  // 5
+  const models = await pythonGenerator.generate(asyncapi);
+  // 6
+  const files = [];
+  // 7
+  for (const model of models) {
+    // 8
+    const modelFileName = `${FormatHelpers.toPascalCase(model.modelName)}.py`;
+    // 9
+    files.push(<File name={modelFileName}>{model.result}</File>);
+  }
+  return files;
+}
+```
+
+Let's break it down. The code snippet above does the following:
+
+1. The `File` component from the [generator react SDK](https://github.com/asyncapi/generator-react-sdk) is needed to handle the further rendering of generated models into files.
+2. The `PythonGenerator` generator is the core needed for model generation. Additionally, you can import [FormatHelpers](https://github.com/asyncapi/modelina/blob/master/src/helpers/FormatHelpers.ts) that provides a set of helpers making it easier to modify model names to match your required case.
+3. You can change the name `schemaRender` to anything else like `modelRenderer`. More importantly, this must be an `async` function and a default export. This function is invoked during generation process and should contain the logic behind models generation.
+4. First, create an instance of the `PythonGenerator` model generator. If you decide to use present functionality from Modelina, you need to pass your presets here during instance creation.
+5. The actual model generation is one line of code, and as a result you get an array of models that later you need to turn into files.
+6. You need to define an array that must be returned from `schemaRender` function. The array must contain React components, and in this case, the `<File>` component.
+7. Iterate over generated models and use their content to create proper definitions of `<File>` components.
+8. Notice how using Modelina helpers, in this case the  `toPascalCase` function, let's you make sure that the filename of your model follows specific case pattern.
+9. Each component must be added into the `files` array that you later return from the default function. Notice the definition of the `<File>` component that enables you to provide the name of resulting file and the content of the model. Notice also `model.result` that shows that initially generated array with models did not contain raw models content but a set of output objects that contain not only `result` but also other info, like for example `modelName`.
+
+With such a model template that uses Modelina, as a result of generation process you would receive a set of model files in `$OUTPUT_DIR/src/models` directory.
+
+## Conclusion
+
+Modelina provides a flexible and powerful way to generate data models from AsyncAPI, OpenAPI, or JSON Schema documents. By integrating Modelina you can much faster enable models generation in your template.

docs/template-development.md

@@ -2,6 +2,8 @@
 title: "Template development"
 weight: 80
 ---
+> **Note**
+> It is advised against attempting to manually template types and models from scratch using the AsyncAPI templating engines such as Nunjucks and React render engines. Instead, it is recommended to use [AsyncAPI Modelina](/docs/tools/generator/model-generation) a dedicated library for model generation.
 
 ## Minimum template requirements
 
@@ -130,7 +132,7 @@ Newer:
 <Text>Version is: **{params.version || asyncapi.info.version()}**</Text>
 ```
 
-Now that you have added all the configuration options, you can start the generation process using the generator CLI. You can pass these parameters via the CLI: `--param name=value or -p name=value`.
+Now that you have added all the configuration options, you can start the generation process using the AsyncAPI CLI. You can pass these parameters via the CLI: `--param name=value or -p name=value`.
 The above configuration helps template users override the existing version with a new version on the command line. (Example: `-p version=2.0.0`)
 
 ## Hooks

docs/template.md

@@ -24,7 +24,7 @@ You can store template projects on a local drive or as a `git` repository during
 
 1. Template is provided as input to the **Generator**.
 2. **asyncapi** is the original AsyncAPI document injected into your template file by default.
-3. **params** are the parameters you pass to the generator CLI. Later, you can also pass these **params** further to other components. 
+3. **params** are the parameters you pass to the AsyncAPI CLI. Later, you can also pass these **params** further to other components. 
 4. The generator passes both the original **asyncapi**, the original AsyncAPI document, and the **params** to the **Template Context**.
 5. Concurrently, the generator passes **Template files** to the **Render engine** as well. AsyncAPI uses two render engines — _react_ and _nunjucks_.
 6. Once the Render Engine receives both the Template Files and the Template Context, it injects all the dynamic values into your react or nunjucks engine, based on the Template Files using the Template Context.

docs/usage.md

@@ -4,10 +4,10 @@ weight: 30
 ---
 
 There are two ways to use the generator:
-- [Generator CLI](#generator-cli)
+- [AsyncAPI CLI](#generator-cli)
 - [Generator library](#using-as-a-modulepackage)
 
-## Generator CLI
+## AsyncAPI CLI
 ```bash
 Usage: asyncapi generate fromTemplate <asyncapi> <template> [<options>]
 
@@ -43,7 +43,7 @@ npm install <folder>
 
 ### Global templates installed with `yarn` or `npm`
 
-You can preinstall templates globally before installing the generator CLI. The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed.
+You can preinstall templates globally before installing the [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/cli). The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed.
 
 ```bash
 npm install -g @asyncapi/[email protected]