docs: add special case for npx

Closes npm#4189
manekinekko · Feb 23, 2022 · d238424 · d238424
1 parent 2b43fb1
commit d238424
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 14 deletions.
diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
@@ -11,10 +11,10 @@ description: Run a command from a local or remote npm package
 <!-- see lib/commands/exec.js -->
 
 ```bash
-npm exec -- <pkg>[@<version>] [args...]
-npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
-npm exec -c '<cmd> [args...]'
-npm exec --package=foo -c '<cmd> [args...]'
+npx -- <pkg>[@<version>] [args...]
+npx --package=<pkg>[@<version>] -- <cmd> [args...]
+npx -c '<cmd> [args...]'
+npx --package=foo -c '<cmd> [args...]'
 
 alias: x
 ```

diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
@@ -35,10 +35,17 @@ const describeUsage = ({ usage }) => {
   synopsis.push('\n```bash')
 
   if (commandName) {
+    let baseCommand = `npm ${commandName}`
+
+    // special case for `npx`
+    if (commandName === 'exec') {
+      baseCommand = 'npx'
+    }
+
     if (!usage) {
-      synopsis.push(`npm ${commandName}`)
+      synopsis.push(baseCommand)
     } else {
-      synopsis.push(usage.map(usageInfo => `npm ${commandName} ${usageInfo}`).join('\n'))
+      synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
     }
 
     const aliases = usageFn(commandName, '').trim()
@@ -99,17 +106,19 @@ try {
   const hasTag = doc.includes(TAGS.CONFIG.START)
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-  let newDoc = params && hasTag ? addDescriptions(doc) : doc
-  newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+  if (params.length) {
+    let newDoc = hasTag ? addDescriptions(doc) : doc
+    newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
-  if (params && !hasTag) {
-    console.error('WARNING: did not find config description section', configDoc)
-  }
+    if (!hasTag) {
+      console.error('WARNING: did not find config description section', configDoc)
+    }
 
-  if (usage && !hasUsageTag) {
-    console.error('WARNING: did not find usage description section', configDoc)
+    if (usage.length && !hasUsageTag) {
+      console.error('WARNING: did not find usage description section', configDoc)
+    }
+    writeFileSync(configDoc, newDoc)
   }
-  writeFileSync(configDoc, newDoc)
 } catch (err) {
   console.error(`WARNING: file cannot be open: ${configDoc}`)
 }