chore: add verbose option to api/typedoc documentation generation script (#1629)

* chore: add verbose option to api/typedoc documentation generation script

* use yargs dependency for doc build script's command line arguments

build/documentation/generate-typedocs.js

@@ -1,9 +1,13 @@
 /**
  * Utility for generating TypeDoc API documentation and placing it in the docs/en/packages folder so it can be hosted by
- * Github pages and viewed through Docusaurus
+ * Github pages and viewed through Docusaurus. 
+ * Contains a dry run command to investigate how the script will operate without actually writing to anything. 
+ * Contains a verbose option to print detailed build output generated by the typedoc processes that create the
+ * api documentation.
  * 
  * Usage :run node build/documentation/generate-typedocs.js OR
  * Usage (dry-run): run node build/documentation/generate-typedocs.js --dry-run
+ * Usage (verbose): run node build/documentation/generate-typedocs.js --verbose 
  */
 
 const path = require("path");
@@ -11,11 +15,11 @@ const fs = require("fs");
 const glob = require("glob");
 const os = require('os');
 const chalk = require('chalk');
+const yargs = require('yargs');
 
 const { exec } = require('child_process');
 const { spawn } = require("child_process");
 
-
 const rootDir = path.resolve(process.cwd());
 const srcDir = "packages/*";
 const destDir = path.join("docs", "en", "packages");
@@ -23,6 +27,7 @@ const destDir = path.join("docs", "en", "packages");
 var copyReadmeScript = 'copy-package-readme.js';
 var copyReadmeScriptPath = path.join('build', 'documentation', copyReadmeScript);
 var dryRun = false;
+var verbose = false;
 
 const excludedPackages = [
     "fast-browser-extensions",
@@ -32,23 +37,12 @@ const excludedPackages = [
 ];
 
 /**
- * Determine if a dry run will be executed based off --dry-run argument being present
- * if an invalid third parameter is entered, the application will exit
+ * Obtain command line aguments
+ * If present when the script is run, their corresponding flags get set to true
  */
-process.argv.forEach(function (val, index) {
-
-    var validArg = true;
-
-    if (index === 2) {
-        val === "--dry-run" ? dryRun = true : validArg = false;
-    }
-
-    if (!validArg) {
-        console.log(chalk.red(`Invalid argument used. To perform a dry-run use --dry-run`));
-        process.exit(1);
-    }
-
-});
+const argv = yargs.argv;
+dryRun = argv.dryRun;
+verbose = argv.verbose;
 
 /**
  * Run the copy readme script, then this one if successful
@@ -142,13 +136,13 @@ function createAPIFiles(packageName, srcPath) {
         }
     });
 
-    // sometimes important errors will get sent to stdout for this process
-    // leaving this here because it's useful for debugging, but generates a lot
-    // of output, makes the terminal output harder to read so it's commented out
-
-    // typedoc.stdout.on('data', (data) => {
-    //     console.error(`${data}`);
-    // });
+    // if set to true, will print detailed build output for typedoc process
+    // useful for debugging
+    if (verbose) {
+        typedoc.stdout.on('data', (data) => {
+            console.log(`${data}`);
+        });
+    }
 
     typedoc.on('error', (err) => {
         console.log(chalk.red(err));

package.json

@@ -18,6 +18,7 @@
   "scripts": {
     "docs:build": "node build/documentation/generate-typedocs.js",
     "docs:build:dry-run": "node build/documentation/generate-typedocs.js --dry-run",
+    "docs:build:verbose": "node build/documentation/generate-typedocs.js --verbose",
     "docs:build:readme": "node build/documentation/copy-package-readme.js",
     "docs:build:api": "node build/documentation/generate-typedocs.js",
     "integration-tests:alpha": "node build/testing/sauce-labs/test-browsers.js alpha",