docs: special case for npx

Closes npm#4189
manekinekko · Feb 24, 2022 · 36e0230 · 36e0230
1 parent d238424
commit 36e0230
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 22 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
-npx -- <pkg>[@<version>] [args...]
-npx --package=<pkg>[@<version>] -- <cmd> [args...]
-npx -c '<cmd> [args...]'
-npx --package=foo -c '<cmd> [args...]'
+npm exec -- <pkg>[@<version>] [args...]
+npm exec --package=<pkg>[@<version>] -- <cmd> [args...]
+npm exec -c '<cmd> [args...]'
+npm exec --package=foo -c '<cmd> [args...]'
 
 alias: x
 ```

diff --git a/docs/content/commands/npx.md b/docs/content/commands/npx.md
@@ -7,6 +7,19 @@ description: Run a command from a local or remote npm package
 ### Synopsis
 
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
+
+```bash
+npx -- <pkg>[@<version>] [args...]
+npx --package=<pkg>[@<version>] -- <cmd> [args...]
+npx -c '<cmd> [args...]'
+npx --package=foo -c '<cmd> [args...]'
+```
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/commands/exec.js -->
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS END -->
 
 ### Description

diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
@@ -31,26 +31,31 @@ const describeAll = (content) =>
 
 const describeUsage = ({ usage }) => {
   const synopsis = []
-  const commandName = commandFile.split('/').pop().split('.')[0]
+
+  // Grab the command name from the *.md filename
+  // NOTE: We cannot use the name property command file because in the case of
+  // `npx` the file being used is `lib/commands/exec.js`
+  const commandName = configDoc.split('/').pop().split('.')[0].replace('npm-', '')
   synopsis.push('\n```bash')
 
   if (commandName) {
-    let baseCommand = `npm ${commandName}`
-
-    // special case for `npx`
-    if (commandName === 'exec') {
-      baseCommand = 'npx'
-    }
-
-    if (!usage) {
-      synopsis.push(baseCommand)
+    // special case for `npx`:
+    // `npx` is not technically a command in and of itself,
+    // so it just needs the usage and parameters of npm exec, and none of the aliases
+    if (commandName === 'npx') {
+      synopsis.push(usage.map(usageInfo => `npx ${usageInfo}`).join('\n'))
     } else {
-      synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
-    }
-
-    const aliases = usageFn(commandName, '').trim()
-    if (aliases) {
-      synopsis.push(`\n${aliases}`)
+      const baseCommand = `npm ${commandName}`
+      if (!usage) {
+        synopsis.push(baseCommand)
+      } else {
+        synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
+      }
+
+      const aliases = usageFn(commandName, '').trim()
+      if (aliases) {
+        synopsis.push(`\n${aliases}`)
+      }
     }
   } else {
     console.error(`could not determine command name from ${commandFile}`)
@@ -106,19 +111,20 @@ try {
   const hasTag = doc.includes(TAGS.CONFIG.START)
   const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-  if (params.length) {
+  if (params?.length) {
     let newDoc = hasTag ? addDescriptions(doc) : doc
     newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
 
     if (!hasTag) {
       console.error('WARNING: did not find config description section', configDoc)
     }
 
-    if (usage.length && !hasUsageTag) {
+    if (usage?.length && !hasUsageTag) {
       console.error('WARNING: did not find usage description section', configDoc)
     }
     writeFileSync(configDoc, newDoc)
   }
 } catch (err) {
   console.error(`WARNING: file cannot be open: ${configDoc}`)
+  console.error(err)
 }