docs: auto-generate npm usage for each command (#4450)

Closes #4189 * docs: auto-generate synopsis sections * feat: improve usage auto-generation' * chore: auto-generate npm usage for each command * docs: print default usage when usage is missing * docs: add special case for npx * fix: remove optional chaining
npm · Feb 24, 2022 · 6b68c1a · 6b68c1a
1 parent d438d61
commit 6b68c1a
Show file tree

Hide file tree

Showing 65 changed files with 821 additions and 164 deletions.
diff --git a/docs/content/commands/npm-access.md b/docs/content/commands/npm-access.md
@@ -6,21 +6,27 @@ description: Set access level on published packages
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/access.js -->
+
 ```bash
 npm access public [<package>]
 npm access restricted [<package>]
-
 npm access grant <read-only|read-write> <scope:team> [<package>]
 npm access revoke <scope:team> [<package>]
-
 npm access 2fa-required [<package>]
 npm access 2fa-not-required [<package>]
-
 npm access ls-packages [<user>|<scope>|<scope:team>]
 npm access ls-collaborators [<package> [<user>]]
 npm access edit [<package>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/access.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Used to set access controls on private packages.

diff --git a/docs/content/commands/npm-adduser.md b/docs/content/commands/npm-adduser.md
@@ -6,12 +6,21 @@ description: Add a registry user account
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/adduser.js -->
+
 ```bash
-npm adduser [--registry=url] [--scope=@orgname] [--auth-type=legacy]
+npm adduser
 
 aliases: login, add-user
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/adduser.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-audit.md b/docs/content/commands/npm-audit.md
@@ -6,13 +6,19 @@ description: Run a security audit
 
 ### Synopsis
 
-```bash
-npm audit [--json] [--production] [--audit-level=(low|moderate|high|critical)]
-npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/audit.js -->
 
-common options: [--production] [--only=(dev|prod)]
+```bash
+npm audit [fix]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/audit.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 The audit command submits a description of the dependencies configured in

diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md
@@ -6,10 +6,19 @@ description: Display npm bin folder
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
 ```bash
-npm bin [-g|--global]
+npm bin
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bin.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-bugs.md b/docs/content/commands/npm-bugs.md
@@ -6,12 +6,21 @@ description: Report bugs for a package in a web browser
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bugs.js -->
+
 ```bash
-npm bugs [<pkgname> [<pkgname> ...]]
+npm bugs [<pkgname>]
 
-aliases: issues
+alias: issues
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/bugs.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command tries to guess at the likely location of a package's bug

diff --git a/docs/content/commands/npm-cache.md b/docs/content/commands/npm-cache.md
@@ -6,18 +6,26 @@ description: Manipulates packages cache
 
 ### Synopsis
 
-```bash
-npm cache add <tarball file>...
-npm cache add <folder>...
-npm cache add <tarball url>...
-npm cache add <name>@<version>...
-
-npm cache clean
-aliases: npm cache clear, npm cache rm
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/cache.js -->
 
+```bash
+npm cache add <tarball file>
+npm cache add <folder>
+npm cache add <tarball url>
+npm cache add <git url>
+npm cache add <name>@<version>
+npm cache clean [<key>]
+npm cache ls [<name>@<version>]
 npm cache verify
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/cache.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-ci.md b/docs/content/commands/npm-ci.md
@@ -6,10 +6,21 @@ description: Install a project with a clean slate
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ci.js -->
+
 ```bash
 npm ci
+
+aliases: clean-install, ic, install-clean, isntall-clean
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/ci.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command is similar to [`npm install`](/commands/npm-install), except

diff --git a/docs/content/commands/npm-completion.md b/docs/content/commands/npm-completion.md
@@ -6,10 +6,19 @@ description: Tab Completion for npm
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
 ```bash
-source <(npm completion)
+npm completion
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/completion.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md
@@ -6,18 +6,25 @@ description: Manage the npm configuration files
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/config.js -->
+
 ```bash
 npm config set <key>=<value> [<key>=<value> ...]
 npm config get [<key> [<key> ...]]
 npm config delete <key> [<key> ...]
 npm config list [--json]
 npm config edit
-npm set <key>=<value> [<key>=<value> ...]
-npm get [<key> [<key> ...]]
 
 alias: c
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/config.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-dedupe.md b/docs/content/commands/npm-dedupe.md
@@ -6,13 +6,21 @@ description: Reduce duplication in the package tree
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dedupe.js -->
+
 ```bash
 npm dedupe
-npm ddp
 
-aliases: ddp
+alias: ddp
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dedupe.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Searches the local package tree and attempts to simplify the overall
@@ -145,6 +153,24 @@ When package package-locks are disabled, automatic pruning of extraneous
 modules will also be disabled. To remove extraneous modules with
 package-locks disabled use `npm prune`.
 
+This configuration does not affect `npm ci`.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
+#### `save`
+
+* Default: `true` unless when using `npm update` or `npm dedupe` where it
+  defaults to `false`
+* Type: Boolean
+
+Save installed packages to a `package.json` file as dependencies.
+
+When used with the `npm rm` command, removes the dependency from
+`package.json`.
+
+Will also prevent writing to `package-lock.json` if set to `false`.
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 

diff --git a/docs/content/commands/npm-deprecate.md b/docs/content/commands/npm-deprecate.md
@@ -6,10 +6,19 @@ description: Deprecate a version of a package
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/deprecate.js -->
+
 ```bash
-npm deprecate <pkg>[@<version range>] <message>
+npm deprecate <pkg>[@<version>] <message>
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/deprecate.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description

diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md
@@ -6,14 +6,19 @@ description: The registry diff command
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/diff.js -->
+
 ```bash
 npm diff [...<paths>]
-npm diff --diff=<pkg-name> [...<paths>]
-npm diff --diff=<version-a> [--diff=<version-b>] [...<paths>]
-npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>]
-npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>]
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/diff.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Similar to its `git diff` counterpart, this command will print diff patches

diff --git a/docs/content/commands/npm-dist-tag.md b/docs/content/commands/npm-dist-tag.md
@@ -6,14 +6,23 @@ description: Modify package distribution tags
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dist-tag.js -->
+
 ```bash
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
 npm dist-tag ls [<pkg>]
 
-aliases: dist-tags
+alias: dist-tags
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/dist-tag.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 Add, remove, and enumerate distribution tags on a package:

diff --git a/docs/content/commands/npm-docs.md b/docs/content/commands/npm-docs.md
@@ -6,12 +6,21 @@ description: Open documentation for a package in a web browser
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/docs.js -->
+
 ```bash
 npm docs [<pkgname> [<pkgname> ...]]
 
-aliases: home
+alias: home
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/docs.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 ### Description
 
 This command tries to guess at the likely location of a package's

diff --git a/docs/content/commands/npm-doctor.md b/docs/content/commands/npm-doctor.md
@@ -6,10 +6,19 @@ description: Check your npm environment
 
 ### Synopsis
 
+<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/doctor.js -->
+
 ```bash
 npm doctor
 ```
 
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/doctor.js -->
+
+<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
+
 Note: This command is unaware of workspaces.
 
 ### Description