Fix and refactor the generate-docs subcommand

[hellodword]

Related to #759

Sorry it should not be the project-folder, but the src folder directly, for example:

should be ./src/test/container-templates/example-templates-sets/simple/src not ./src/test/container-templates/example-templates-sets/simple

So I rename it in order to avoid the confusing.

[samruddhikhandale]

Looks good to me! We already merged this new command, hence, this might be a breaking change for folks. However, I don't believe this might be utilized yet as we have not updated our *-starter repos.

[chrmarti]

The package and publish commands use a positional argument for this, should we align the doc command with those. E.g. from the publish command:

devcontainer features publish <target>

Package and publish Features

Positionals:
  target
           Package and publish features at provided [target] (default is cwd), where [target] is either:
              1. A path
           to the src folder of the collection with [1..n] features.
              2. A path to a single feature that contains a d
           evcontainer-feature.json.
                                                                                      [string] [required] [default: "."]

Options:
      --help       Show help                                                                                   [boolean]
      --version    Show version number                                                                         [boolean]
  -r, --registry   Name of the OCI registry.                                               [string] [default: "ghcr.io"]
  -n, --namespace  Unique indentifier for the collection of features. Example: <owner>/<repo>        [string] [required]
      --log-level  Log level.                                      [choices: "info", "debug", "trace"] [default: "info"]

[hellodword]

The package and publish commands use a positional argument for this, should we align the doc command with those. E.g. from the publish command:

devcontainer features publish <target>

Package and publish Features

Positionals:
  target
           Package and publish features at provided [target] (default is cwd), where [target] is either:
              1. A path
           to the src folder of the collection with [1..n] features.
              2. A path to a single feature that contains a d
           evcontainer-feature.json.
                                                                                      [string] [required] [default: "."]

Options:
      --help       Show help                                                                                   [boolean]
      --version    Show version number                                                                         [boolean]
  -r, --registry   Name of the OCI registry.                                               [string] [default: "ghcr.io"]
  -n, --namespace  Unique indentifier for the collection of features. Example: <owner>/<repo>        [string] [required]
      --log-level  Log level.                                      [choices: "info", "debug", "trace"] [default: "info"]

You're right, it's better, I'll switch to this

[chrmarti]

Looks good, left a few comments.

[chrmarti]

Use async variant to allow other code to make progress while this is waiting for completion.

[chrmarti]

Should we keep --project-folder and -p as a hidden option with a warning message in the log when used for compatibility? Since this has been available for a few weeks users might have picked it up and removing it could break things locally or in CIs.