docs: add documents and postinstallation scripts for ag deprecation

.changeset/start_clijs_deprecation.md

@@ -0,0 +1,7 @@
+---
+"@asyncapi/generator": minor
+---
+
+Start deprecating `ag` in the generator repository. The purpose of deprecating the `ag` option for documentation generation is to move people's
+attention to use the `AsyncAPI CLI` in order to maintain a single entry point for all the AsyncAPI tools. 
+Otherwise, the maintainers need to manually update the `ag` option in the generator repository every time a new version of the `AsyncAPI CLI` is released.

README.md

@@ -9,7 +9,8 @@ This is a Monorepo managed using [Turborepo](https://turbo.build/) and contains
 
 ![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)
 
-> warning: This package doesn't support AsyncAPI 1.x anymore. We recommend to upgrade to the latest AsyncAPI version using the [AsyncAPI converter](https://github.com/asyncapi/converter-js) (You can refer to [installation guide](/apps/generator//docs//installation-guide.md)). If you need to convert documents on the fly, you may use the [Node.js](https://github.com/asyncapi/converter-js) or [Go](https://github.com/asyncapi/converter-go) converters.
+[!IMPORTANT]
+Deprecation Notice: The use of ag for documentation generation is deprecated and will be removed in future releases. We strongly encourage migrating to the new AsyncAPI CLI.
 
 <!-- toc is generated with GitHub Actions do not remove toc markers -->
 

apps/generator/docs/deprecate-cli.js-ag.md

@@ -0,0 +1,79 @@
+---
+title: "Deprecate ag"
+weight: 170
+---
+
+# Migration Guide from “ag/asyncapi-generator” to AsyncAPI CLI
+
+## Overview
+With the introduction of the AsyncAPI CLI, the use of `ag` for documentation generation in the AsyncAPI generator repository is being deprecated. This guide provides detailed instructions on how to transition from `ag` to the new AsyncAPI CLI.
+
+## Why Migrate?
+- **Enhanced Features:** The AsyncAPI CLI offers advanced features and improvements.
+- **Consistency:** Ensures consistent command usage across different environments.
+- **Support and Maintenance:** Future updates and support will focus on the AsyncAPI CLI.
+
+## Deprecated `ag/asyncapi-generator` Options and Their AsyncAPI CLI Equivalents
+Here is a list of `ag/asyncapi-generator` options and their equivalents in the AsyncAPI CLI:
+
+- **-d, --disable-hook [hooks...]**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --disable-hook <hookType>=<hookName>`
+
+- **--debug**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --debug`
+
+- **-i, --install**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --install`
+
+- **-n, --no-overwrite <glob>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --no-overwrite <glob>`
+
+- **-o, --output <outputDir>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --output <outputDir>`
+
+- **-p, --param <name=value>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --param <name=value>`
+
+- **--force-write**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --force-write`
+
+- **--watch-template**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --watch`
+
+- **--map-base-url <url:folder>**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --map-base-url <url:folder>`
+
+## Migration Steps
+
+### 1. Install AsyncAPI CLI
+First, ensure you have the AsyncAPI CLI installed:
+```
+npm install -g @asyncapi/cli
+```
+
+### 2. Update Your Commands
+Replace the deprecated ag commands with their AsyncAPI CLI equivalents. Below are examples of how to update your commands:
+**Example Migration**:
+**Before Migration (Using ag)**:
+```
+ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+**After Migration (Using AsyncAPI CLI)**:
+```
+asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+### 3. Verify and Test
+Run the updated commands to ensure they work as expected. Verify the output and ensure that all files are generated correctly.
+
+## Additional Resources
+**CLI Documentation**: [AsyncAPI CLI Documentation](https://www.asyncapi.com/docs/tools/cli)
+**Installation**: [AsyncAPI CLI Installation](https://www.asyncapi.com/docs/tools/cli/installation)
+**Usage**: [AsyncAPI CLI Usage](https://www.asyncapi.com/docs/tools/cli/usage)
+**Support**: For any issues or questions, please create an issue in our [CLI repository](https://github.com/asyncapi/cli).
+
+## Conclusion
+By following this migration guide, you can smoothly transition from ag to the AsyncAPI CLI, taking advantage of its enhanced features and improved performance. If you have any questions or need further assistance, feel free to contact us.
+
+Happy coding!

apps/generator/package.json

@@ -25,7 +25,8 @@
     "lint:tpl:validator": "eslint --fix --config ../../.eslintrc ../../.github/templates-list-validator",
     "generate:readme:toc": "markdown-toc -i README.md",
     "generate:assets": "npm run docs && npm run generate:readme:toc",
-    "bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION"
+    "bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION",
+    "postinstall": "node ./scripts/postinstall.js"
   },
   "preferGlobal": true,
   "bugs": {

apps/generator/scripts/postinstall.js

@@ -0,0 +1,33 @@
+const migrationGuideUrl = '../docs/deprecate-cli.js-ag.md';
+const installationGuideUrl = 'https://github.com/asyncapi/website/blob/master/assets/docs/fragments/cli-installation.md';
+
+console.log(`
+*************************************
+*                                   *
+*  DEPRECATION NOTICE               *
+*                                   *
+*************************************
+
+The use of 'ag' for documentation generation is deprecated and will be removed in future releases.
+
+Please migrate to the new AsyncAPI CLI using the following guide:
+
+1. Install AsyncAPI CLI:
+   $ npm install -g @asyncapi/cli
+   For other installation methods, visit ${installationGuideUrl}
+
+2. Update your commands:
+   Replace the deprecated 'ag' commands with their AsyncAPI CLI equivalents.
+
+Example Migration:
+
+Before Migration (Using 'ag'):
+$ ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+
+After Migration (Using AsyncAPI CLI):
+$ asyncapi generate fromTemplate ./asyncapi.yaml ./template --output ./output --param param1=value1 --debug --install --disable-hook hookType=hookName
+
+For more details, please visit: ${migrationGuideUrl}
+
+Thank you for your understanding and cooperation.
+`);