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

1 files changed, 46 insertions, 0 deletions

diff --git a/scripts/config-doc-command.js b/scripts/config-doc-command.js
new file mode 100644
index 000000000..d7f734ed5
--- /dev/null
+++ b/scripts/config-doc-command.js
@@ -0,0 +1,46 @@
+const { definitions } = require('../lib/utils/config/index.js')
+const { writeFileSync, readFileSync } = require('fs')
+const { resolve, basename, relative } = require('path')
+
+const configDoc = process.argv[2]
+const commandFile = process.argv[3]
+
+// Note: commands without params skip this whole process.
+const { params } = require(resolve(commandFile))
+
+const describeAll = () =>
+  params.map(name => definitions[name].describe()).join('\n\n')
+
+const addBetweenTags = (doc, startTag, endTag, body) => {
+  const startSplit = doc.split(startTag)
+  if (startSplit.length !== 2)
+    throw new Error('Did not find exactly one start tag')
+
+  const endSplit = startSplit[1].split(endTag)
+  if (endSplit.length !== 2)
+    throw new Error('Did not find exactly one end tag')
+
+  return [
+    startSplit[0],
+    startTag,
+    '\n<!-- automatically generated, do not edit manually -->\n',
+    body,
+    '\n\n',
+    endTag,
+    endSplit[1],
+  ].join('')
+}
+
+const addDescriptions = doc => {
+  const startTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->'
+  const endTag = '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->'
+  return addBetweenTags(doc, startTag, endTag, describeAll())
+}
+
+// always write SOMETHING so that Make sees the file is up to date.
+const doc = readFileSync(configDoc, 'utf8')
+const hasTag = doc.includes('<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->')
+const newDoc = params && hasTag ? addDescriptions(doc) : doc
+if (params && !hasTag)
+  console.error('WARNING: did not find config description section', configDoc)
+writeFileSync(configDoc, newDoc)