readme is missing documentation for the new commands

[Souvikns]

Oclif has a way to generate command help documentation if we are going with that we just need to set it up.

[fmvilas]

Yeah, just watch out that it might generate documentation of commands separated by colons (:) instead of spaces.

[BOLT04]

Hi @Souvikns 👋, automating this would be really interesting so that when we add new commands, the docs on the README are automatically updated. I had a look on the package.json and there is already a script for the readme, are we already using it on GitHub actions?

I'd like to help with this issue if no one is working on it 🙂. I messed around with oclif readme command to see the output, and I just want to clarify if the generated docs are correct:

Usage

$ npm install -g @asyncapi/cli
$ asyncapi COMMAND
running command...
$ asyncapi (-v|--version|version)
@asyncapi/cli/0.12.7 linux-x64 node-v16.13.0
$ asyncapi --help [COMMAND]
USAGE
  $ asyncapi COMMAND
...

Commands

• asyncapi config
• asyncapi config:context
• asyncapi config:context:add CONTEXT-NAME SPEC-FILE-PATH
• asyncapi config:context:current
• asyncapi config:context:list
• asyncapi config:context:remove CONTEXT-NAME
• asyncapi config:context:use CONTEXT-NAME
• asyncapi new
• asyncapi start
• asyncapi start:studio
• asyncapi validate [SPEC-FILE]

asyncapi config

access configs

USAGE
  $ asyncapi config

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config.ts

asyncapi config:context

USAGE
  $ asyncapi config context

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context.ts

asyncapi config:context:add CONTEXT-NAME SPEC-FILE-PATH

Add or modify a context in the store

USAGE
  $ asyncapi config context add CONTEXT-NAME SPEC-FILE-PATH

ARGUMENTS
  CONTEXT-NAME    context name
  SPEC-FILE-PATH  file path of the spec file

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context/add.ts

asyncapi config:context:current

Shows the current context that is being used

USAGE
  $ asyncapi config context current

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context/current.ts

asyncapi config:context:list

List all the stored context in the store

USAGE
  $ asyncapi config context list

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context/list.ts

asyncapi config:context:remove CONTEXT-NAME

Delete a context from the store

USAGE
  $ asyncapi config context remove CONTEXT-NAME

ARGUMENTS
  CONTEXT-NAME  Name of the context to delete

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context/remove.ts

asyncapi config:context:use CONTEXT-NAME

Set a context as current

USAGE
  $ asyncapi config context use CONTEXT-NAME

ARGUMENTS
  CONTEXT-NAME  name of the saved context

OPTIONS
  -h, --help  show CLI help

See code: src/commands/config/context/use.ts

asyncapi new

creates a new asyncapi file

USAGE
  $ asyncapi new

OPTIONS
  -e, --example=example      name of the example to use
  -h, --help                 show CLI help
  -n, --file-name=file-name  name of the file
  -p, --port=port            port in which to start Studio
  -s, --studio               open in Studio
  --no-tty                   do not use an interactive terminal

See code: src/commands/new.ts

asyncapi start

starts a new local instance of Studio

USAGE
  $ asyncapi start

OPTIONS
  -h, --help  show CLI help

See code: src/commands/start.ts

asyncapi start:studio

starts a new local instance of Studio

USAGE
  $ asyncapi start studio

OPTIONS
  -f, --file=file  path to the AsyncAPI file to link with Studio
  -h, --help       show CLI help
  -p, --port=port  port in which to start Studio

See code: src/commands/start/studio.ts

asyncapi validate [SPEC-FILE]

validate asyncapi file

USAGE
  $ asyncapi validate [SPEC-FILE]

ARGUMENTS
  SPEC-FILE  spec path, url, or context-name

OPTIONS
  -h, --help  show CLI help

See code: src/commands/validate.ts

Unfortunately, I wasn't able to test the current CLI commands by installing the asyncapi/cli package, I believe this error: [MODULE_NOT_FOUND] Error Plugin: @asyncapi/cli: Cannot find module '@oclif/plugin-help/lib/command' Require stack: is related to #192 😢

Feel free to give me any feedback on my assumption, I appreciate it 👍.

[Souvikns]

Awesome @BOLT04 the generated docs are correct 👍🏻. No one is working on this issue as of now so you can take it up.

Yeah the CLI is kinda breaking in production but it works fine in the development and you can just clone the repo and run /bin/run in the project to run the CLI. Currently working on https://github.com/asyncapi/cli/pull/203 to fix the issue. I think you have to wait for this as we are updating oclif version and the oclif readme command might work differently from right now.

[derberg]

the only problem with the generated stuff is : that should be spaces. So asyncapi config:context is actually asyncapi config context

[Souvikns]

The new version has some inbuilt support for topic separators maybe this would help.

[BOLT04]

ok, then for this issue we'll wait on #203 👍 . Then setup the topicSeparator on the package.json and build a new workflow to automatically run this script when there is a push to master. The next step would be to open a PR with those changes to be merged.

Is there a better way to run this script what does everyone think?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[BOLT04]

hi @Souvikns, since #203 is done could we resume this issue, wdyt 🙂 ?

[Souvikns]

@BOLT04, cli documentation was a part of GSoD, but don't know what is the status. https://github.com/asyncapi/website/issues/602, https://github.com/asyncapi/cli/issues/232 were planned for this. I don't know if anyone is working on CLI documentation right now. Give me some time, I will check on the status and update you.

[imabp]

@Souvikns we can continue on the CLI command reference using this tool And I will be writing the getting started document

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[derberg]

I think this one is still valid

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[derberg]

this is still valid, although I'm not sure what the solution is

[derberg]

Ok, looks like thanks to the fact that we recently upgraded to almost latest oclif version, we can use oclif readme command.

So the scope for this one is:

• use oclif readme to generate all commands doc
• generated docs should be added to https://github.com/asyncapi/cli/blob/master/docs/usage.md
• this command and any additional needed scripts should run as npm script added to generate:assets script. So no new CI workflows are needed - in theory

I will add this issue to trial of AsyncAPI Bounty -> https://github.com/orgs/asyncapi/discussions/541#discussioncomment-5532370

[thulieblack]

This issue is part of the AsyncAPI Bounty Program, interested contributors need to follow the guidelines below to ensure fairness and timely completion of assigned tasks:

Task Assignment

The assignment of tasks will be prioritized in the following order:

• AsyncAPI maintainers (from any repository)
• Regular contributors (individuals who have merged three or more pull requests)
• Other (if an individual doesn't fall under the above, the maintainer can determine the criteria i.e regular volunteers, etc)

We encouraged everyone to apply as long as the task is for you (falls under your skill set). We will not be using the first comment - get assigned method for assignments. Instead, we will provide 3 days to consider all individuals interested before assigning any bounty task.

Deadline

To maintain accountability and ensure the timely completion of the deadline for this task will be 4- 6 weeks from the date of assignment. If a contributor requires an extension on their task, it should be communicated and approved by the maintainer.

Issue Tracking and Updates

Contributors must provide weekly updates on the task they are working on to help maintainers stay informed of progress. If a contributor fails to provide an update, they will be reminded via a ping. If a contributor fails to provide an update after three pings over three weeks, we will assume they have silently dropped the issue, and it will be reassigned to someone else.

Issue Drop-outs

Any contributor who drops an assigned issue will be penalized and will not be eligible to participate in the bounty program for 6 months. We understand that unforeseen circumstances can arise, and dropping an assigned issue may be unavoidable in some cases. However, we believe that enforcing this penalty is necessary to ensure the effectiveness of the bounty program, respect maintainer time, and honor the efforts of other contributors who could have solved the issue but were unable to do so due to the drop-out.

We encourage all contributors to follow these guidelines to ensure a fair and timely completion of tasks assigned through our bounty program.

[mhmohona]

I would like to work on this issue.

[derberg]

@mhmohona I just assigned this issue to you to make it clear for others you work on it

@mediba123 we actually have automation that updates table of contents in readme and also a contribution guide. Did you check it before making that comment? 😄

[thulieblack]

@mhmohona how is the task going so far??

[mhmohona]

Hello @thulieblack, I am alsmot done with the task.

[derberg]

@mhmohona hey, so it looks like automation worked, scripts got triggered and we got https://github.com/asyncapi/cli/pull/601 but as you can see, commands section is empty 🤔

[derberg]

@mhmohona I'm pretty sure it is because of some delay on oclif readme command, and the JS code just needs to wait.

can you open a followup PR with fix like below:

/* 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 readContents();
    // 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();

async function readContents() {
  let readmeContents;
  let commandsContent = '';

  while (commandsContent.length === 0) {
    readmeContents = await readFile(README_PATH, 'utf8');
    
    // Check if the content between <!-- commands --> and <!-- commandsstop --> is empty
    const commandsStartText = '<!-- commands -->';
    const commandStartIndex = readmeContents.indexOf(commandsStartText);
    const commandStopIndex = readmeContents.indexOf('<!-- commandsstop -->');
    //cutting the content between the above mentioned tags, removing white spaces and checking if there is some text as it will mean text was added by oclif
    commandsContent = readmeContents.slice(commandStartIndex + commandsStartText.length, commandStopIndex).trim();

    if (commandsContent.length === 0) {
      console.log('No content between <!-- commands --> and <!-- commandsstop -->. Trying again...');
    } else {
      console.log('Content found!');
    }

    await delay(3000); // 3-second delay
  }

  return readmeContents;
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

[mhmohona]

Thank you so much for pointing this @derberg! I have updated the code and created new PR.

I thought of adding it but then thought it might be unnecessary but it seems it is needed. :3

[derberg]

ok, so 😄 it didn't work

workflow was running for over 3min and below was just logged out

No content between <!-- commands --> and <!-- commandsstop -->. Trying again...

I don't think it is normal so I cancelled the run. Not sure yet what is the solution

[derberg]

I can't figure from their code what might be wrong, but we can log more things in the GitHub Action

so please open another PR with change in the package.json where you run oclif readme so it is DEBUG=* oclif readme

so basically make sure it says "generate:readme:commands": "cd scripts && DEBUG=* oclif readme",

this will give us a lot of insights and info where it stucks with commands generation

[asyncapi-bot]

:tada: This issue has been resolved in version 0.45.1 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket:

[derberg]

@mhmohona is still doesn't work, logs show

2023-05-30T04:42:52.932Z config:@asyncapi/cli loading IDs from /home/runner/work/cli/cli/lib/commands
2023-05-30T04:42:52.939Z config:@asyncapi/cli found commands []

while on local I get

config:@asyncapi/cli loading IDs from /Users/wookiee/sources/cli/lib/commands +0ms
  config:@asyncapi/cli found commands [
  'bundle',                'convert',
  'diff',                  'optimize',
  'validate',              'config',
  'config:versions',       'generate:fromTemplate',
  'generate',              'generate:models',
  'new:file',              'new:glee',
  'new',                   'new:project',
  'start',                 'start:studio',
  'config:context:add',    'config:context:current',
  'config:context',        'config:context:list',
  'config:context:remove', 'config:context:use'
]

so looks like oclif cannot figure what commands are available, but I do not know why

[derberg]

we could add a step in CI that checks run: ls /home/runner/work/cli/cli/lib/commands as maybe it is empty but I'm not sure, I'm kinda sure /home/runner/work/cli/cli is correct.

[derberg]

@mhmohona congrats, topic completed. Look what we got on the website thanks to your work ❤️ -> https://www.asyncapi.com/docs/tools/cli/usage

@thulieblack another bounty issue completed, over to you

cc @Souvikns fyi usage docs are not automatically updated 💪🏼

[thulieblack]

Hey, @mhmohona, congratulations on completing your issue!!

This is how'll claim your bounty:

1. Go to AsyncAPI Open Collective page
2. Submit an expense and add details for the bounty issue
3. Voila! You get your coins🤑 !!