chore(docs): move scripts and refactor

All docs related scripts are now located in the docs workspace

Makefile

@@ -4,8 +4,6 @@ SHELL = bash
 PUBLISHTAG = $(shell node scripts/publish-tag.js)
 BRANCH = $(shell git rev-parse --abbrev-ref HEAD)
 
-markdowns = $(shell find docs -name '*.md' | grep -v 'index')
-
 # these docs have the @VERSION@ tag in them, so they have to be rebuilt
 # whenever the package.json is touched, in case the version changed.
 version_mandocs = $(shell grep -rl '@VERSION@' docs/content \
@@ -18,11 +16,11 @@ cli_mandocs = $(shell find docs/content/commands -name '*.md' \
 
 files_mandocs = $(shell find docs/content/configuring-npm -name '*.md' \
                |sed 's|.md|.5|g' \
-               |sed 's|docs/content/configuring-npm/|man/man5/|g' ) \
+               |sed 's|docs/content/configuring-npm/|man/man5/|g' )
 
 misc_mandocs = $(shell find docs/content/using-npm -name '*.md' \
                |sed 's|.md|.7|g' \
-               |sed 's|docs/content/using-npm/|man/man7/|g' ) \
+               |sed 's|docs/content/using-npm/|man/man7/|g' )
 
 mandocs = $(cli_mandocs) $(files_mandocs) $(misc_mandocs)
 
@@ -41,7 +39,7 @@ $(version_mandocs): package.json
 
 htmldocs: deps
 	node bin/npm-cli.js rebuild cmark-gfm
-	node bin/npm-cli.js run build -w docs 
+	node docs/bin/dockhand.js
 
 clean: docsclean gitclean
 
@@ -52,36 +50,35 @@ deps:
 	node bin/npm-cli.js run resetdeps
 
 ## targets for man files, these are encouraged to be only built by running `make docs` or `make mandocs`
-man/man1/%.1: docs/content/commands/%.md scripts/docs-build.js
+man/man1/%.1: docs/content/commands/%.md docs/bin/docs-build.js
 	@[ -d man/man1 ] || mkdir -p man/man1
-	node scripts/docs-build.js $< $@
+	node docs/bin/docs-build.js $< $@
 
 man/man5/npm-json.5: man/man5/package.json.5
 	cp $< $@
 
 man/man5/npm-global.5: man/man5/folders.5
 	cp $< $@
 
-man/man5/%.5: docs/content/configuring-npm/%.md scripts/docs-build.js
+man/man5/%.5: docs/content/configuring-npm/%.md docs/bin/docs-build.js
 	@[ -d man/man5 ] || mkdir -p man/man5
-	node scripts/docs-build.js $< $@
+	node docs/bin/docs-build.js $< $@
 
-man/man7/%.7: docs/content/using-npm/%.md scripts/docs-build.js
+man/man7/%.7: docs/content/using-npm/%.md docs/bin/docs-build.js
 	@[ -d man/man7 ] || mkdir -p man/man7
-	node scripts/docs-build.js $< $@
+	node docs/bin/docs-build.js $< $@
 
 # Any time the config definitions description changes, automatically
 # update the documentation to account for it
-docs/content/using-npm/config.md: scripts/config-doc.js lib/utils/config/*.js
-	node scripts/config-doc.js
+docs/content/using-npm/config.md: docs/bin/config-doc.js lib/utils/config/*.js
+	node docs/bin/config-doc.js
 
-docs/content/commands/npm-%.md: lib/commands/%.js scripts/config-doc-command.js lib/utils/config/*.js
-	node scripts/config-doc-command.js $@ $<
+docs/content/commands/npm-%.md: docs/bin/config-doc-command.js lib/commands/%.js lib/utils/config/*.js lib/utils/cmd-list.js
+	node docs/bin/config-doc-command.js $@ $<
 
 freshdocs:
 	touch lib/utils/config/definitions.js
-	touch scripts/config-doc-command.js
-	touch scripts/config-doc.js
+	touch "docs/bin/*.js"
 	make docs
 
 test: deps

docs/.gitignore

@@ -18,5 +18,6 @@
 !/.gitignore
 !/bin/
 !/content/
+!/lib/
 !/nav.yml
 !/package.json

scripts/config-doc-command.js → docs/bin/config-doc-command.js

@@ -1,35 +1,14 @@
-const { definitions } = require('../lib/utils/config/index.js')
-const cmdAliases = require('../lib/utils/cmd-list').aliases
-const { writeFileSync, readFileSync } = require('fs')
+const fs = require('fs').promises
 const { resolve } = require('path')
-
-const configDoc = process.argv[2]
-const commandFile = process.argv[3]
-
-const TAGS = {
-  CONFIG: {
-    START: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->',
-    END: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->',
-  },
-  USAGE: {
-    START: '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->',
-    END: '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->',
-  },
-}
-
-// Note: commands without params skip this whole process.
-const {
-  params,
-  usage,
-} = require(resolve(commandFile))
+const { definitions, aliases } = require('../lib/npm.js')
 
 const describeAll = (content) =>
   content.map(name => definitions[name].describe()).join(
     '\n\n<!-- automatically generated, do not edit manually -->\n' +
       '<!-- see lib/utils/config/definitions.js -->\n\n'
   )
 
-const describeUsage = ({ usage }) => {
+const describeUsage = ({ usage, configDoc, commandFile }) => {
   const synopsis = []
 
   // Grab the command name from the *.md filename
@@ -52,19 +31,19 @@ const describeUsage = ({ usage }) => {
         synopsis.push(usage.map(usageInfo => `${baseCommand} ${usageInfo}`).join('\n'))
       }
 
-      const aliases = Object.keys(cmdAliases).reduce((p, c) => {
-        if (cmdAliases[c] === commandName) {
+      const cmdAliases = Object.keys(aliases).reduce((p, c) => {
+        if (aliases[c] === commandName) {
           p.push(c)
         }
         return p
       }, [])
 
-      if (aliases.length === 1) {
+      if (cmdAliases.length === 1) {
         synopsis.push('')
-        synopsis.push(`alias: ${aliases[0]}`)
-      } else if (aliases.length > 1) {
+        synopsis.push(`alias: ${cmdAliases[0]}`)
+      } else if (cmdAliases.length > 1) {
         synopsis.push('')
-        synopsis.push(`aliases: ${aliases.join(', ')}`)
+        synopsis.push(`aliases: ${cmdAliases.join(', ')}`)
       }
     }
   } else {
@@ -106,35 +85,58 @@ const addBetweenTags = (
   ].join('')
 }
 
-const addDescriptions = doc =>
+const TAGS = {
+  CONFIG: {
+    START: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->',
+    END: '<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->',
+  },
+  USAGE: {
+    START: '<!-- AUTOGENERATED USAGE DESCRIPTIONS START -->',
+    END: '<!-- AUTOGENERATED USAGE DESCRIPTIONS END -->',
+  },
+}
+
+const addDescriptions = ({ doc, params }) =>
   addBetweenTags(doc, TAGS.CONFIG.START, TAGS.CONFIG.END, describeAll(params))
 
-const addUsageDescriptions = doc =>
+const addUsageDescriptions = ({ doc, usage, configDoc, commandFile }) =>
   addBetweenTags(doc, TAGS.USAGE.START, TAGS.USAGE.END,
-    describeUsage({ usage }),
+    describeUsage({ usage, configDoc, commandFile }),
     commandFile
   )
 
-try {
-  // always write SOMETHING so that Make sees the file is up to date.
-  const doc = readFileSync(configDoc, 'utf8')
-  const hasTag = doc.includes(TAGS.CONFIG.START)
-  const hasUsageTag = doc.includes(TAGS.USAGE.START)
+const run = async (configDoc, commandFile) => {
+  try {
+    // Note: commands without params skip this whole process.
+    const { params, usage } = require(resolve(commandFile))
 
-  if (params && params.length) {
-    let newDoc = hasTag ? addDescriptions(doc) : doc
-    newDoc = hasUsageTag ? addUsageDescriptions(newDoc) : newDoc
+    // always write SOMETHING so that Make sees the file is up to date.
+    const doc = await fs.readFile(configDoc, 'utf8')
+    const hasTag = doc.includes(TAGS.CONFIG.START)
+    const hasUsageTag = doc.includes(TAGS.USAGE.START)
 
-    if (!hasTag) {
-      console.error('WARNING: did not find config description section', configDoc)
-    }
+    if (params && params.length) {
+      let newDoc = hasTag ? addDescriptions({ doc, params }) : doc
+      newDoc = hasUsageTag
+        ? addUsageDescriptions({ doc: newDoc, usage, configDoc, commandFile })
+        : newDoc
+
+      if (!hasTag) {
+        console.error('WARNING: did not find config description section', configDoc)
+      }
 
-    if ((usage && usage.length) && !hasUsageTag) {
-      console.error('WARNING: did not find usage description section', configDoc)
+      if ((usage && usage.length) && !hasUsageTag) {
+        console.error('WARNING: did not find usage description section', configDoc)
+      }
+      await fs.writeFile(configDoc, newDoc)
     }
-    writeFileSync(configDoc, newDoc)
+  } catch (err) {
+    console.error(`WARNING: file cannot be open: ${configDoc}`)
+    throw err
   }
-} catch (err) {
-  console.error(`WARNING: file cannot be open: ${configDoc}`)
-  console.error(err)
 }
+
+run(...process.argv.slice(2)).catch((err) => {
+  process.exitCode = 1
+  console.error(err)
+})

scripts/config-doc.js → docs/bin/config-doc.js

@@ -1,7 +1,6 @@
-const { shorthands, describeAll } = require('../lib/utils/config/index.js')
-const { writeFileSync, readFileSync } = require('fs')
-const { resolve } = require('path')
-const configDoc = resolve(__dirname, '../docs/content/using-npm/config.md')
+const fs = require('fs').promises
+const { resolve, relative } = require('path')
+const { shorthands, describeAll } = require('../lib/npm.js')
 
 const addBetweenTags = (doc, startTag, endTag, body) => {
   const startSplit = doc.split(startTag)
@@ -49,6 +48,16 @@ const addShorthands = doc => {
   return addBetweenTags(doc, startTag, endTag, body)
 }
 
-const doc = readFileSync(configDoc, 'utf8')
-writeFileSync(configDoc, addDescriptions(addShorthands(doc)))
-console.log(`updated docs/content/using-npm/config.md`)
+const run = async (dir) => {
+  const configDoc = resolve(dir, '../content/using-npm/config.md')
+  const doc = await fs.readFile(configDoc, 'utf8')
+
+  await fs.writeFile(configDoc, addDescriptions(addShorthands(doc)))
+
+  return `updated ${relative(process.cwd(), configDoc)}`
+}
+
+run(__dirname).then(console.log).catch((err) => {
+  process.exitCode = 1
+  console.error(err)
+})

docs/bin/dockhand.js

@@ -1,41 +1,11 @@
-#!/usr/bin/env node
-
 const path = require('path')
 const fs = require('fs')
 const yaml = require('yaml')
 const cmark = require('cmark-gfm')
 const mdx = require('@mdx-js/mdx')
 const mkdirp = require('mkdirp')
 const jsdom = require('jsdom')
-const npm = require('../../lib/npm.js')
-
-const run = async function (rootDir) {
-  const dir = (...p) => path.join(rootDir, '..', ...p)
-
-  const config = require(dir('bin', 'config.json'))
-  const template = fs.readFileSync(dir('bin', 'template.html'), 'utf-8')
-  const nav = yaml.parse(fs.readFileSync(dir('nav.yml'), 'utf-8'))
-
-  try {
-    const navPaths = getNavigationPaths(nav)
-    const fsPaths = await renderFilesystemPaths({
-      input: dir('content'),
-      output: dir('output'),
-      config,
-      template,
-    })
-
-    const navErrors = ensureNavigationComplete(navPaths, fsPaths)
-    if (navErrors) {
-      console.error(navErrors)
-      process.exit(1)
-    }
-  } catch (error) {
-    console.error(error)
-  }
-}
-
-run(__dirname)
+const { version: VERSION } = require('../lib/npm.js')
 
 function ensureNavigationComplete (navPaths, fsPaths) {
   const unmatchedNav = {}
@@ -124,7 +94,7 @@ async function renderFile (root, outputRoot, childPath, { template, config }) {
   const inputPath = path.join(root, childPath)
 
   if (!inputPath.match(/\.md$/)) {
-    console.log(`warning: unknown file type ${inputPath}, ignored`)
+    console.error(`warning: unknown file type ${inputPath}, ignored`)
     return
   }
 
@@ -140,7 +110,7 @@ async function renderFile (root, outputRoot, childPath, { template, config }) {
   })
 
   // Replace any tokens in the source
-  md = md.replace(/@VERSION@/, npm.version)
+  md = md.replace(/@VERSION@/, VERSION)
 
   // Render the markdown into an HTML snippet using a GFM renderer.
   const content = cmark.renderHtmlSync(md, {
@@ -190,7 +160,7 @@ async function renderFile (root, outputRoot, childPath, { template, config }) {
         return config[key.replace(/^config\./, '')]
 
       default:
-        console.log(`warning: unknown token '${token}' in ${inputPath}`)
+        console.error(`warning: unknown token '${token}' in ${inputPath}`)
         return ''
     }
   })
@@ -323,3 +293,30 @@ class MarkdownError extends Error {
     this.inner = inner
   }
 }
+
+const run = async function (rootDir) {
+  const dir = (...p) => path.join(rootDir, '..', ...p)
+
+  const config = require(dir('lib', 'config.json'))
+  const template = fs.readFileSync(dir('lib', 'template.html'), 'utf-8')
+  const nav = yaml.parse(fs.readFileSync(dir('nav.yml'), 'utf-8'))
+
+  const navPaths = getNavigationPaths(nav)
+  const fsPaths = await renderFilesystemPaths({
+    input: dir('content'),
+    output: dir('output'),
+    config,
+    template,
+  })
+
+  const navErrors = ensureNavigationComplete(navPaths, fsPaths)
+  if (navErrors) {
+    console.error(navErrors)
+    throw new Error('Nav Errors')
+  }
+}
+
+run(__dirname).catch((err) => {
+  process.exitCode = 1
+  console.error(err)
+})