Integrate jsdoc-to-markdown as a build-docs command.

lib/commands/build-docs.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const jsdocToMd = require('jsdoc-to-markdown');
+const path = require('path');
+const { $ } = require('zx');
+const { readFile, writeFile } = require('fs').promises;
+
+const { loadConfig } = require('../utils');
+
+module.exports = {
+  command: path.parse(__filename).name,
+  describe: 'Builds the README.md file from the JSDoc in the codebase.',
+  handler: async () => {
+    $.verbose = false;
+    const cwd = process.cwd();
+    const readmePath = path.resolve(cwd, 'README.md');
+    const { docs } = await loadConfig();
+    const { files, headingDepth, noGfm, template } = docs || {};
+    const templatePath = template || path.resolve(cwd, 'docs', 'templates', 'README.hbs');
+    const templateData = await readFile(templatePath, 'utf8');
+    const cfg = {
+      files: (Array.isArray(files) && files) || ['./lib/**/*.js'],
+      'heading-depth': headingDepth ?? 2,
+      'no-gfm': noGfm ?? false,
+      template: templateData
+    };
+    const output = await jsdocToMd.render(cfg);
+    await writeFile(readmePath, output, 'utf8');
+    await $`git add ./README.md`;
+  }
+};

lib/commands/test.js

@@ -4,15 +4,15 @@ const merge = require('merge-options');
 const path = require('path');
 const { $ } = require('zx');
 
-const { readConfig } = require('../utils');
+const { loadConfig } = require('../utils');
 
 module.exports = {
   command: path.parse(__filename).name,
   describe: 'Run tests with Jest.',
   handler: async () => {
     $.verbose = false;
     await $`mkdir -p ./reports`;
-    const { test } = await readConfig();
+    const { test } = await loadConfig();
     const baseCfg = {
       collectCoverage: true,
       collectCoverageFrom: ['**/*.js'],

lib/utils.js

@@ -7,17 +7,17 @@ const { readFile } = require('fs').promises;
 const { name } = require('../package.json');
 
 /**
- * Reads the configuration for this tool from the target package.json file.
+ * Loads the configuration for this tool from the target package.json file.
  *
  * @returns {Promise<Object>}
  */
-async function readConfig() {
+async function loadConfig() {
   try {
     const { filepath } = await cosmiconfig(name, {
       searchPlaces: ['package.json']
     }).search();
     const pkg = JSON.parse(await readFile(filepath, 'utf8'));
-    return pkg[name];
+    return pkg[name] || {};
   } catch {
     return {};
   }
@@ -33,4 +33,4 @@ function pathFromCwd(...args) {
   return path.relative(process.cwd(), path.resolve(...args));
 }
 
-module.exports = { pathFromCwd, readConfig };
+module.exports = { loadConfig, pathFromCwd };