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 /scripts | |
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 'scripts')
-rw-r--r-- | scripts/config-doc-command.js | 46 |
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) |