docs: update usage documentation for new commands

.github/workflows/update-docs-on-docs-commits.yml

@@ -0,0 +1,37 @@
+name: 'Update generated parts of documentation on docs: commits'
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  docs-gen:
+    name: 'Generate docs and create PR'
+    # PR should be created within this GH action only if it is a docs: commit
+    # Otherwise it will conflict with release workflow
+    if: startsWith(github.event.commits[0].message, 'docs:')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install dependencies
+        run: npm ci
+      - name: Regenerate docs
+        run: npm run generate:assets --if-present
+      - name: Create Pull Request with updated docs
+        if: startsWith(github.event.commits[0].message, 'docs:')
+        uses: peter-evans/create-pull-request@v3
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          commit-message: 'chore: update generated docs'
+          committer: asyncapi-bot <[email protected]>
+          author: asyncapi-bot <[email protected]>
+          title: 'chore: update generated docs'
+          body: 'Update of docs that are generated and were forgotten on PR level.'
+          branch: gen-docs-update
+

package.json

@@ -155,7 +155,10 @@
     "build": "rimraf lib && node scripts/fetch-asyncapi-example.js && tsc && echo \"Build Completed\"",
     "bump:version": "npm --no-git-tag-version --allow-same-version version $VERSION",
     "dev": "tsc --watch",
-    "generate:assets": "npm run generate:readme:toc",
+    "generate:readme:create": "printf '\n\n# Usage\n\n<!-- usage -->\n\n# Commands\n\n<!-- commands -->\n' > scripts/README.md",
+    "generate:readme:commands": "cd scripts && oclif readme",
+    "generate:assets": "npm run generate:readme:toc && npm run generate:commands",
+    "generate:commands": "npm run generate:readme:create && npm run generate:readme:commands && node ./scripts/updateUsageDocs.js && rimraf ./scripts/README.md",
     "generate:readme:toc": "markdown-toc -i README.md",
     "lint": "eslint --max-warnings 0 --config .eslintrc .",
     "lint:fix": "eslint --max-warnings 5 --config .eslintrc . --fix",

scripts/updateUsageDocs.js

@@ -0,0 +1,43 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const {writeFile, readFile} = require('fs').promises;
+
+// Define the paths to the README and usage files
+const README_PATH = './scripts/README.md'; // File path for the generated README file
+const USAGE_PATH = './docs/usage.md'; // File path for the usage documentation file
+
+const header = `---
+title: 'Usage'
+weight: 40
+---
+
+<!-- 
+
+This file is automatically generated from updateUsageDocs.js script. In package.json in line 158-161 lines the following steps has been executed in order to run this script successfully - 
+
+* generate:readme:create: It creates the initial content for the README file by printing the usage and commands tags using printf and redirects the output to scripts/README.md file.
+* generate:readme:commands: It changes the directory to the scripts folder and executes the oclif readme command. This command generates the usage and commands sections based on the CLI commands and updates the content in the scripts/README.md file.
+* generate:assets: This script combines the two previously mentioned scripts (generate:readme:toc and generate:commands) to generate the necessary assets, such as the README file and usage documentation.
+* generate:commands: This script executes the following steps:
+ - Runs the generate:readme:create script to create the initial content for the README file.
+ - Executes the generate:readme:commands script to generate the usage and commands sections based on the CLI commands.
+ - Runs the updateUsageDocs.js script using Node.js to update the usage documentation file with the contents of the generated README file.
+ - Deletes the scripts/README.md file using the rimraf command.
+
+-->
+
+The AsyncAPI CLI makes it easier to work with AsyncAPI documents.
+`;
+
+// Define an async function to write the header and the README contents to the usage documentation file
+async function run() {
+  try {
+    await writeFile(USAGE_PATH, header);
+    const readmeContents = await readFile(README_PATH, 'utf8');
+    // Append the contents of the README file to the usage documentation file
+    await writeFile(USAGE_PATH, readmeContents, { flag: 'a' });
+  } catch (e) {
+    console.error(e);
+  }
+}
+
+run();