[DOCS] Synopsis sections are not auto generated.

[utamori]

Is there an existing issue for this?

• I have searched the existing issues

This issue exists in the latest npm version

• I am using the latest npm

Current Behavior

I found that npm create <initializer> behaves the same way as npm init <initializer>, but there seems to be no mention of it in the documentation

Expected Behavior

To have Documentation

Steps To Reproduce

1. npm v8.3.0
2. Run npm create vue
3. It works fine. create-vue

Environment

• npm:

[wraithgar]

The # Synopsis sections of the docs are not being auto-generated like the front matter and the config descriptions.

[bnb]

this feeels like less of a synopsis issue and more of a "there's no documentation for npm create" 👀

[wraithgar]

They're aliases. npm init is the real command. If you run npm create -h you will see that the output is all npm init and it says that create is one of its aliases.

[bnb]

that's true, but the docs site has no reference (about it being an alias) to npm create. this creates a weird situation where if someone were to recommend, I use npm create but I go try to figure out how to use it from the docs, I have no path to actually learning about it.

[manekinekko]

Hey, I am trying to send a fix for this issue, but I am confused because I can see the synopsis being generated. Here is the one for npm init:

Has this issue been already fixed?

[wraithgar]

You'll notice that synopsis does not match the output of npm init -h. It was manually generated. The -h output in the cli is auto generated using the usage and params entries in each given command, and should also be the basis for the synopsis in each commands' md file

https://github.com/npm/cli/blob/latest/docs/content/commands/npm-init.md?plain=1#L7-L14

Notice how the configuration section has notes about it being auto generated

https://github.com/npm/cli/blob/latest/docs/content/commands/npm-init.md?plain=1#L146

scripts/config-doc-command.js is what does this, and would need to be extended to also replace the Synopsis section with both the Usage and Options output. And preferrably the aliases too.

[manekinekko]

Oh! I see. I think I get it. I will work on this and send a fix.

[manekinekko]

@wraithgar are you ok with me updating all lib/commands/*.js file to include the alias and options entry so they can be printed into the docs/commands/*.md files?

I'd like to validate this change before going over all 66 files. Here is a preview of the change I need to make to each commands files:

[wraithgar]

@manekinekko I don't think you need to edit the js files. It's supposed to work the other way around. The content in the .md files is out of date and the .js files are the ones that we've already gone through and made say what we want, a lot of unneeded context was removed and/or moved to other parts of the .md. The .js files should drive the .md content.

Aliases for any given cmd name can be done like this

> require('./lib/utils/usage.js')('init', '').trim()
'aliases: create, innit'

Usage like this

require('./lib/commands/init.js').usage.map(u => `npm init ${u}`).join('\n')
'npm init [--force|-f|--yes|-y|--scope]\n' +
  'npm init <@scope> (same as `npx <@scope>/create`)\n' +
  'npm init [<@scope>/]<name> (same as `npx [<@scope>/]create-<name>`)'

The "command options" are already being powered by the .js and populating the Configuration section.

[wraithgar]

See here how the "run without positional args" part of the old synopsis is already duplicated elsewhere in the description of npm exec https://docs.npmjs.com/cli/v7/commands/npm-exec#description

[manekinekko]

Fantastic! Thanks for pointing this out. I will take care of this then :)