fix(docs): autogenerate config docs for commands

Add a script and Makefile rule to build the "Configuration" section for
all command documentation based on the command classes' `params` list.

Also correct several minor problems in the documentation, and add
`params` listings for commands that were lacking them, to match the
existing documentation and/or behavior within the code.

PR-URL: #3243
Credit: @isaacs
Close: #3243
Reviewed-by: @wraithgar

Makefile

@@ -73,6 +73,9 @@ man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js
 docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js
 	node scripts/config-doc.js
 
+docs/content/commands/npm-%.md: lib/%.js scripts/config-doc-command.js lib/utils/config/*.js
+	node scripts/config-doc-command.js $@ $<
+
 test: dev-deps
 	node bin/npm-cli.js test
 

docs/content/commands/npm-access.md

@@ -81,6 +81,30 @@ fail with an HTTP 402 status code (logically enough), unless you use
 
 Management of teams and team memberships is done with the `npm team` command.
 
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `registry`
+
+* Default: "https://registry.npmjs.org/"
+* Type: URL
+
+The base URL of the npm registry.
+
+#### `otp`
+
+* Default: null
+* Type: null or String
+
+This is a one-time password from a two-factor authenticator. It's needed
+when publishing or changing package permissions with `npm access`.
+
+If not set, and a registry response fails with a challenge for a one-time
+password, npm will prompt on the command line for one.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See Also
 
 * [`libnpmaccess`](https://npm.im/libnpmaccess)

docs/content/commands/npm-adduser.md

@@ -35,37 +35,46 @@ your existing record.
 
 ### Configuration
 
-#### registry
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `registry`
 
-Default: https://registry.npmjs.org/
+* Default: "https://registry.npmjs.org/"
+* Type: URL
 
-The base URL of the npm package registry. If `scope` is also specified,
-this registry will only be used for packages with that scope. `scope` defaults
-to the scope of the project directory you're currently in, if any. See [`scope`](/using-npm/scope).
+The base URL of the npm registry.
 
-#### scope
+#### `scope`
 
-Default: none
+* Default: the scope of the current project, if any, or ""
+* Type: String
 
-If specified, the user and login credentials given will be associated
-with the specified scope. See [`scope`](/using-npm/scope). You can use both at the same time,
-e.g.
+Associate an operation with a scope for a scoped registry.
 
-```bash
-npm adduser --registry=http://myregistry.example.com --scope=@myco
+Useful when logging in to or out of a private registry:
+
+```
+# log in, linking the scope to the custom registry
+npm login --scope=@mycorp --registry=https://registry.mycorp.com
+
+# log out, removing the link and the auth token
+npm logout --scope=@mycorp
 ```
 
-This will set a registry for the given scope and login or create a user for
-that registry at the same time.
+This will cause `@mycorp` to be mapped to the registry for future
+installation of packages specified according to the pattern
+`@mycorp/package`.
 
-#### auth-type
+This will also cause `npm init` to create a scoped package.
+
+```
+# accept all defaults, and create a package named "@foo/whatever",
+# instead of just named "whatever"
+npm init --scope=@foo --yes
+```
 
-* Default: `'legacy'`
-* Type: `'legacy'`, `'sso'`, `'saml'`, `'oauth'`
 
-What authentication strategy to use with `adduser`/`login`. Some npm registries
-(for example, npmE) might support alternative auth strategies besides classic
-username/password entry in legacy npm.
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
 
@@ -74,3 +83,5 @@ username/password entry in legacy npm.
 * [npmrc](/configuring-npm/npmrc)
 * [npm owner](/commands/npm-owner)
 * [npm whoami](/commands/npm-whoami)
+* [npm token](/commands/npm-token)
+* [npm profile](/commands/npm-profile)

docs/content/commands/npm-audit.md

@@ -187,6 +187,92 @@ Fail an audit only if the results include a vulnerability with a level of modera
 $ npm audit --audit-level=moderate
 ```
 
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `audit-level`
+
+* Default: null
+* Type: null, "info", "low", "moderate", "high", "critical", or "none"
+
+The minimum level of vulnerability for `npm audit` to exit with a non-zero
+exit code.
+
+#### `dry-run`
+
+* Default: false
+* Type: Boolean
+
+Indicates that you don't want npm to make any changes and that it should
+only report what it would have done. This can be passed into any of the
+commands that modify your local installation, eg, `install`, `update`,
+`dedupe`, `uninstall`, as well as `pack` and `publish`.
+
+Note: This is NOT honored by other network related commands, eg `dist-tags`,
+`owner`, etc.
+
+#### `force`
+
+* Default: false
+* Type: Boolean
+
+Removes various protections against unfortunate side effects, common
+mistakes, unnecessary performance degradation, and malicious input.
+
+* Allow clobbering non-npm files in global installs.
+* Allow the `npm version` command to work on an unclean git repository.
+* Allow deleting the cache folder with `npm cache clean`.
+* Allow installing packages that have an `engines` declaration requiring a
+  different version of npm.
+* Allow installing packages that have an `engines` declaration requiring a
+  different version of `node`, even if `--engine-strict` is enabled.
+* Allow `npm audit fix` to install modules outside your stated dependency
+  range (including SemVer-major changes).
+* Allow unpublishing all versions of a published package.
+* Allow conflicting peerDependencies to be installed in the root project.
+* Implicitly set `--yes` during `npm init`.
+
+If you don't have a clear idea of what you want to do, it is strongly
+recommended that you do not use this option!
+
+#### `json`
+
+* Default: false
+* Type: Boolean
+
+Whether or not to output JSON data, rather than the normal output.
+
+Not supported by all npm commands.
+
+#### `package-lock-only`
+
+* Default: false
+* Type: Boolean
+
+If set to true, it will update only the `package-lock.json`, instead of
+checking `node_modules` and downloading dependencies.
+
+#### `omit`
+
+* Default: 'dev' if the `NODE_ENV` environment variable is set to
+  'production', otherwise empty.
+* Type: "dev", "optional", or "peer" (can be set multiple times)
+
+Dependency types to omit from the installation tree on disk.
+
+Note that these dependencies _are_ still resolved and added to the
+`package-lock.json` or `npm-shrinkwrap.json` file. They are just not
+physically installed on disk.
+
+If a package type appears in both the `--include` and `--omit` lists, then
+it will be included.
+
+If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
+variable will be set to `'production'` for all lifecycle scripts.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See Also
 
 * [npm install](/commands/npm-install)

docs/content/commands/npm-bin.md

@@ -16,6 +16,26 @@ Note: This command is unaware of workspaces.
 
 Print the folder where npm will install executables.
 
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `global`
+
+* Default: false
+* Type: Boolean
+
+Operates in "global" mode, so that packages are installed into the `prefix`
+folder instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See Also
 
 * [npm prefix](/commands/npm-prefix)

docs/content/commands/npm-bugs.md

@@ -21,24 +21,28 @@ will search for a `package.json` in the current folder and use the `name` proper
 
 ### Configuration
 
-#### browser
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `browser`
 
 * Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`
-* Type: String or Boolean
+* Type: null, Boolean, or String
 
-The browser that is called by the `npm bugs` command to open websites.
+The browser that is called by npm commands to open websites.
 
 Set to `false` to suppress browser behavior and instead print urls to
 terminal.
 
 Set to `true` to use default system URL opener.
 
-#### registry
+#### `registry`
 
-* Default: https://registry.npmjs.org/
-* Type: url
+* Default: "https://registry.npmjs.org/"
+* Type: URL
 
-The base URL of the npm package registry.
+The base URL of the npm registry.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
 

docs/content/commands/npm-cache.md

@@ -75,11 +75,17 @@ verify`.
 
 ### Configuration
 
-#### cache
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `cache`
 
-Default: `~/.npm` on Posix, or `%AppData%/npm-cache` on Windows.
+* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm`
+* Type: Path
 
-The root cache folder.
+The location of npm's cache directory. See [`npm
+cache`](/commands/npm-cache)
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also
 

docs/content/commands/npm-ci.md

@@ -65,6 +65,32 @@ cache:
   - "$HOME/.npm"
 ```
 
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `ignore-scripts`
+
+* Default: false
+* Type: Boolean
+
+If true, npm does not run scripts specified in package.json files.
+
+Note that commands explicitly intended to run a particular script, such as
+`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`
+will still run their intended script if `ignore-scripts` is set, but they
+will *not* run any pre- or post-scripts.
+
+#### `script-shell`
+
+* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
+* Type: null or String
+
+The shell to use for scripts run with the `npm exec`, `npm run` and `npm
+init <pkg>` commands.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See Also
 
 * [npm install](/commands/npm-install)

docs/content/commands/npm-config.md

@@ -93,6 +93,50 @@ npm config edit
 Opens the config file in an editor.  Use the `--global` flag to edit the
 global config.
 
+### Configuration
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+#### `json`
+
+* Default: false
+* Type: Boolean
+
+Whether or not to output JSON data, rather than the normal output.
+
+Not supported by all npm commands.
+
+#### `global`
+
+* Default: false
+* Type: Boolean
+
+Operates in "global" mode, so that packages are installed into the `prefix`
+folder instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
+#### `editor`
+
+* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on
+  Windows, or 'vim' on Unix systems
+* Type: String
+
+The command to run for `npm edit` and `npm config edit`.
+
+#### `long`
+
+* Default: false
+* Type: Boolean
+
+Show extended information in `ls`, `search`, and `help-search`.
+
+<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
+
 ### See Also
 
 * [npm folders](/configuring-npm/folders)