From 36e0230f2ec7bd0beea3629a6c8a46d42a6bc8f7 Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Thu, 24 Feb 2022 10:38:45 +0100
Subject: [PATCH] docs: special case for npx

Closes #4189
---
 docs/content/commands/npm-exec.md |  8 +++---
 docs/content/commands/npx.md      | 13 ++++++++++
 scripts/config-doc-command.js     | 42 ++++++++++++++++++-------------
 3 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/docs/content/commands/npm-exec.md b/docs/content/commands/npm-exec.md
index 674bb95524200..3645e336b9da9 100644
--- 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
index 510b04c3d9ee1..e7e59d00d84c1 100644
--- 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
index c25361d89cad3..5b1e7689ea6dd 100644
--- 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,7 +111,7 @@ 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
 
@@ -114,11 +119,12 @@ try {
       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)
 }