diff options
author | isaacs <i@izs.me> | 2021-05-13 23:46:30 +0300 |
---|---|---|
committer | Gar <gar+gh@danger.computer> | 2021-05-14 18:39:54 +0300 |
commit | 2f5c28a68719e948d2efedf463ebcb35972aaefb (patch) | |
tree | 69b3c3d7aa81decaaccbe4c11831f16f12301180 /tap-snapshots | |
parent | 3bd758387f0f4668ae1eb2bfe420051da2a74c8e (diff) |
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: https://github.com/npm/cli/pull/3243
Credit: @isaacs
Close: #3243
Reviewed-by: @wraithgar
Diffstat (limited to 'tap-snapshots')
-rw-r--r-- | tap-snapshots/test/lib/publish.js.test.cjs | 2 | ||||
-rw-r--r-- | tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs | 54 | ||||
-rw-r--r-- | tap-snapshots/test/lib/utils/npm-usage.js.test.cjs | 153 |
3 files changed, 187 insertions, 22 deletions
diff --git a/tap-snapshots/test/lib/publish.js.test.cjs b/tap-snapshots/test/lib/publish.js.test.cjs index 0d652e289..7d5e7a9c5 100644 --- a/tap-snapshots/test/lib/publish.js.test.cjs +++ b/tap-snapshots/test/lib/publish.js.test.cjs @@ -14,7 +14,7 @@ Usage: npm publish [<folder>] Options: -[--tag <tag>] [--access <restricted|public>] [--dry-run] +[--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] diff --git a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs index 53aef86f7..48aea0303 100644 --- a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs +++ b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs @@ -373,6 +373,7 @@ mistakes, unnecessary performance degradation, and malicious input. 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! @@ -491,6 +492,11 @@ CI setup. 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. + #### \`include\` * Default: @@ -567,10 +573,7 @@ number, if not already set in package.json. Whether or not to output JSON data, rather than the normal output. -This feature is currently experimental, and the output data structures for -many commands is either not implemented in JSON yet, or subject to change. -Only the output from \`npm ls --json\` and \`npm search --json\` are currently -valid. +Not supported by all npm commands. #### \`key\` @@ -630,6 +633,8 @@ two conditions are met: * the globally installed version is identical to the version that is being installed locally. +When used with \`npm ls\`, only show packages that are linked. + #### \`local-address\` * Default: null @@ -662,7 +667,7 @@ The maximum number of log files to store. * Default: false * Type: Boolean -Show extended information in \`npm ls\` and \`npm search\`. +Show extended information in \`ls\`, \`search\`, and \`help-search\`. #### \`maxsockets\` @@ -723,8 +728,8 @@ allow the CLI to fill in missing cache data, see \`--prefer-offline\`. #### \`omit\` -* Default: 'dev' if the NODE_ENV environment variable is set to 'production', - otherwise empty. +* 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. @@ -943,16 +948,29 @@ or \`--save-optional\` are true. Associate an operation with a scope for a scoped registry. -Useful when logging in to a private registry for the first time: +Useful when logging in to or out of a private registry: -\`\`\`bash +\`\`\` +# 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 cause \`@mycorp\` to be mapped to the registry for future installation of packages specified according to the pattern \`@mycorp/package\`. +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 +\`\`\` + + #### \`script-shell\` * Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows @@ -1061,6 +1079,9 @@ then it will install the specified tag. Also the tag that is added to the package@version specified by the \`npm tag\` command, if no explicit tag is given. +When used by the \`npm diff\` command, this is the tag used to fetch the +tarball that will be compared with the local files by default. + #### \`tag-version-prefix\` * Default: "v" @@ -1109,7 +1130,7 @@ other files are created with a mode of 0o644. #### \`unicode\` * Default: false on windows, true on mac/unix systems with a unicode locale, - as defined by the LC_ALL, LC_CTYPE, or LANG environment variables. + as defined by the \`LC_ALL\`, \`LC_CTYPE\`, or \`LANG\` environment variables. * Type: Boolean When set to true, npm uses unicode characters in the tree output. When @@ -1204,9 +1225,16 @@ Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option. -Valid values for the \`workspace\` config are either: - Workspace names - Path -to a workspace directory - Path to a parent workspace directory (will result -to selecting all of the nested workspaces) +Valid values for the \`workspace\` config are either: + +* Workspace names +* Path to a workspace directory +* Path to a parent workspace directory (will result to selecting all of the + nested workspaces) + +When set for the \`npm init\` command, this may be set to the folder of a +workspace which does not yet exist, to create the folder and set it up as a +brand new workspace within the project. This value is not exported to the environment for child processes. diff --git a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs index 84ffc44e3..661deec26 100644 --- a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs +++ b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs @@ -180,6 +180,9 @@ All commands: npm access ls-collaborators [<package> [<user>]] npm access edit [<package>] + Options: + [--registry <registry>] [--otp <otp>] + Run "npm help access" for more info adduser npm adduser @@ -205,7 +208,8 @@ All commands: Options: [--audit-level <info|low|moderate|high|critical|none>] [--dry-run] [-f|--force] - [--json] [--package-lock-only] [--production] + [--json] [--package-lock-only] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] Run "npm help audit" for more info @@ -228,6 +232,9 @@ All commands: Usage: npm bugs [<pkgname>] + Options: + [--browser|--browser <browser>] [--registry <registry>] + alias: issues Run "npm help bugs" for more info @@ -245,6 +252,9 @@ All commands: npm cache clean npm cache verify + Options: + [--cache <cache>] + Run "npm help cache" for more info ci npm ci @@ -254,6 +264,9 @@ All commands: Usage: npm ci + Options: + [--ignore-scripts] [--script-shell <script-shell>] + aliases: clean-install, ic, install-clean, isntall-clean Run "npm help ci" for more info @@ -278,6 +291,9 @@ All commands: npm config list [--json] npm config edit + Options: + [--json] [-g|--global] [--editor <editor>] [-l|--long] + alias: c Run "npm help config" for more info @@ -289,6 +305,11 @@ All commands: Usage: npm dedupe + Options: + [--global-style] [--legacy-bundling] [--strict-peer-deps] [--package-lock] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts] + [--audit] [--bin-links] [--fund] [--dry-run] + alias: ddp Run "npm help dedupe" for more info @@ -300,6 +321,9 @@ All commands: Usage: npm deprecate <pkg>[@<version>] <message> + Options: + [--registry <registry>] [--otp <otp>] + Run "npm help deprecate" for more info diff npm diff @@ -313,6 +337,12 @@ All commands: npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>] npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>] [...<paths>] + Options: + [--diff <diff> [--diff <diff> ...]] [--diff-name-only] + [--diff-unified <diff-unified>] [--diff-ignore-all-space] [--diff-no-prefix] + [--diff-src-prefix <diff-src-prefix>] [--diff-dst-prefix <diff-dst-prefix>] + [--diff-text] [-g|--global] [--tag <tag>] + Run "npm help diff" for more info dist-tag npm dist-tag @@ -355,6 +385,9 @@ All commands: Usage: npm doctor + Options: + [--registry <registry>] + Run "npm help doctor" for more info edit npm edit @@ -364,6 +397,9 @@ All commands: Usage: npm edit <pkg>[/<subpkg>...] + Options: + [--editor <editor>] + Run "npm help edit" for more info exec npm exec @@ -377,6 +413,8 @@ All commands: npm exec --package=foo -c '<cmd> [args...]' Options: + [--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]] + [-c|--call <call>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] @@ -391,6 +429,9 @@ All commands: Usage: npm explain <folder | specifier> + Options: + [--json] + alias: why Run "npm help explain" for more info @@ -402,6 +443,9 @@ All commands: Usage: npm explore <pkg> [ -- <command>] + Options: + [--shell <shell>] + Run "npm help explore" for more info find-dupes npm find-dupes @@ -411,6 +455,11 @@ All commands: Usage: npm find-dupes + Options: + [--global-style] [--legacy-bundling] [--strict-peer-deps] [--package-lock] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts] + [--audit] [--bin-links] [--fund] + Run "npm help find-dupes" for more info fund npm fund @@ -443,6 +492,9 @@ All commands: Usage: npm help <term> [<terms..>] + Options: + [--viewer <viewer>] + alias: hlep Run "npm help help" for more info @@ -457,6 +509,9 @@ All commands: npm hook rm <id> npm hook update <id> <url> <secret> + Options: + [--registry <registry>] [--otp <otp>] + Run "npm help hook" for more info init npm init @@ -469,6 +524,7 @@ All commands: npm init [<@scope>/]<name> (same as \`npx [<@scope>/]create-<name>\`) Options: + [-y|--yes] [-f|--force] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] @@ -494,7 +550,10 @@ All commands: Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer] - [-E|--save-exact] + [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] + [--strict-peer-deps] [--package-lock] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts] + [--audit] [--bin-links] [--fund] [--dry-run] aliases: i, in, ins, inst, insta, instal, isnt, isnta, isntal, add @@ -507,6 +566,9 @@ All commands: Usage: npm install-ci-test + Options: + [--ignore-scripts] [--script-shell <script-shell>] + alias: cit Run "npm help install-ci-test" for more info @@ -529,7 +591,10 @@ All commands: Options: [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer] - [-E|--save-exact] + [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] + [--strict-peer-deps] [--package-lock] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts] + [--audit] [--bin-links] [--fund] [--dry-run] alias: it @@ -543,6 +608,13 @@ All commands: npm link (in package dir) npm link [<@scope>/]<pkg>[@<version>] + Options: + [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer] + [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling] + [--strict-peer-deps] [--package-lock] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts] + [--audit] [--bin-links] [--fund] [--dry-run] + alias: ln Run "npm help link" for more info @@ -554,6 +626,11 @@ All commands: Usage: npm ll [[<@scope>/]<pkg> ...] + Options: + [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--link] + [--unicode] + alias: la Run "npm help ll" for more info @@ -591,6 +668,11 @@ All commands: Usage: npm ls npm ls [[<@scope>/]<pkg> ...] + Options: + [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] [--depth <depth>] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--link] + [--unicode] + alias: list Run "npm help ls" for more info @@ -604,6 +686,9 @@ All commands: npm org rm orgname username npm org ls orgname [<username>] + Options: + [--registry <registry>] [--otp <otp>] [--json] [-p|--parseable] + alias: ogr Run "npm help org" for more info @@ -615,6 +700,9 @@ All commands: Usage: npm outdated [[<@scope>/]<pkg> ...] + Options: + [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] + Run "npm help outdated" for more info owner npm owner @@ -626,6 +714,9 @@ All commands: npm owner rm <user> [<@scope>/]<pkg> npm owner ls [<@scope>/]<pkg> + Options: + [--registry <registry>] [--otp <otp>] + alias: author Run "npm help owner" for more info @@ -663,6 +754,9 @@ All commands: Usage: npm prefix [-g] + Options: + [-g|--global] + Run "npm help prefix" for more info profile npm profile @@ -675,6 +769,9 @@ All commands: npm profile get [<key>] npm profile set <key> <value> + Options: + [--registry <registry>] [--json] [-p|--parseable] [--otp <otp>] + Run "npm help profile" for more info prune npm prune @@ -685,7 +782,8 @@ All commands: npm prune [[<@scope>/]<pkg>...] Options: - [--production] + [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--dry-run] + [--json] Run "npm help prune" for more info @@ -697,7 +795,7 @@ All commands: npm publish [<folder>] Options: - [--tag <tag>] [--access <restricted|public>] [--dry-run] + [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] [-ws|--workspaces] @@ -710,6 +808,9 @@ All commands: Usage: npm rebuild [[<@scope>/]<name>[@<version>] ...] + Options: + [-g|--global] [--bin-links] [--ignore-scripts] + alias: rb Run "npm help rebuild" for more info @@ -735,6 +836,9 @@ All commands: Usage: npm restart [-- <args>] + Options: + [--ignore-scripts] [--script-shell <script-shell>] + Run "npm help restart" for more info root npm root @@ -758,7 +862,8 @@ All commands: Options: [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]] - [-ws|--workspaces] + [-ws|--workspaces] [--if-present] [--ignore-scripts] + [--script-shell <script-shell>] aliases: run, rum, urn @@ -772,7 +877,9 @@ All commands: npm search [search terms ...] Options: - [-l|--long] [--json] [-p|--parseable] [--no-description] + [-l|--long] [--json] [--color|--color <always>] [-p|--parseable] + [--no-description] [--searchopts <searchopts>] [--searchexclude <searchexclude>] + [--registry <registry>] [--prefer-online] [--prefer-offline] [--offline] aliases: s, se, find @@ -816,6 +923,9 @@ All commands: Usage: npm star [<pkg>...] + Options: + [--registry <registry>] [--unicode] + Run "npm help star" for more info stars npm stars @@ -825,6 +935,9 @@ All commands: Usage: npm stars [<user>] + Options: + [--registry <registry>] + Run "npm help stars" for more info start npm start @@ -834,6 +947,9 @@ All commands: Usage: npm start [-- <args>] + Options: + [--ignore-scripts] [--script-shell <script-shell>] + Run "npm help start" for more info stop npm stop @@ -843,6 +959,9 @@ All commands: Usage: npm stop [-- <args>] + Options: + [--ignore-scripts] [--script-shell <script-shell>] + Run "npm help stop" for more info team npm team @@ -856,6 +975,9 @@ All commands: npm team rm <scope:team> <user> [--otp <otpcode>] npm team ls <scope>|<scope:team> + Options: + [--registry <registry>] [--otp <otp>] [-p|--parseable] [--json] + Run "npm help team" for more info test npm test @@ -865,6 +987,9 @@ All commands: Usage: npm test [-- <args>] + Options: + [--ignore-scripts] [--script-shell <script-shell>] + aliases: tst, t Run "npm help test" for more info @@ -878,6 +1003,10 @@ All commands: npm token revoke <id|token> npm token create [--read-only] [--cidr=list] + Options: + [--read-only] [--cidr <cidr> [--cidr <cidr> ...]] [--registry <registry>] + [--otp <otp>] + Run "npm help token" for more info uninstall npm uninstall @@ -901,6 +1030,9 @@ All commands: Usage: npm unpublish [<@scope>/]<pkg>[@<version>] + Options: + [-f|--force] + Run "npm help unpublish" for more info unstar npm unstar @@ -910,6 +1042,9 @@ All commands: Usage: npm unstar [<pkg>...] + Options: + [--registry <registry>] [--unicode] [--otp <otp>] + Run "npm help unstar" for more info update npm update @@ -920,7 +1055,9 @@ All commands: npm update [<pkg>...] Options: - [-g|--global] + [-g|--global] [--global-style] [--legacy-bundling] [--strict-peer-deps] + [--package-lock] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] + [--ignore-scripts] [--audit] [--bin-links] [--fund] [--dry-run] aliases: up, upgrade, udpate |