chore: update automation process for docusaurus documentation generation (#1340)

build/documentation/copy-package-readme.js

@@ -1,6 +1,9 @@
 /**
- * Utility for copying readme to .docs/en/packages/[package-name]/readme.md.
- * Usage: node build/documentation/copy-package-readme.js
+ * Utility for copying and mocking the copying of readme files from packages to .docs/en/packages/[package-name]/readme.md.
+ * Usage (copy):run node build/documentation/copy-package-readme.js OR
+ *              npm run docs:build
+ * Usage (dry-run):run node build/documentation/copy-package-readme.js --dry-run OR
+ *                 npm run docs:dry-run
  */
 const path = require("path");
 const fs = require("fs");
@@ -9,14 +12,15 @@ const glob = require("glob");
 const rootDir = path.resolve(process.cwd());
 const srcReadmePaths = "packages/*/README.md";
 const destDir = path.join("docs", "en", "packages");
+const srcSidebar = path.join("website", "sidebars.json");
 
 var dryRun = false;
+var sidebarEntries = [];
 
 /**
  * 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
  */
-
 process.argv.forEach(function (val, index) {
 
     var validArg = true;
@@ -26,39 +30,118 @@ process.argv.forEach(function (val, index) {
     }
 
     if (!validArg) {
-        console.log('Invalid argument used. To perform a dry-run use --dry-run');
+        console.log('\x1b[31m%s\x1b[0m', 'Invalid argument used. To perform a dry-run use --dry-run');
         process.exit(1);
     }
+
 });
 
 /**
- * Function to copy readme files to the docs/en/packages folder
+ * Function to copy readme files to the ./docs/en/packages folder
+ * and update Docusaurus sidebar, ./website/sidebars.json
  */
 function copyReadmeFiles() {
 
-    const resolvedSrcReadmePaths = path.resolve(rootDir, srcReadmePaths);
+    if (dryRun) console.log("In docs/en/packages/, this script would...");
 
-    glob(resolvedSrcReadmePaths, {realpath:true}, function(error, files) {
-        
-        files.forEach((filePath) => {
-            const destReadmePath = filePath.replace(/(\bpackages\b)(?!.*\1)/, destDir);
-            const dirPath = path.dirname(destReadmePath);
-            if (!fs.existsSync(dirPath)) {
-                dryRun ? console.log("----> Would create folder " + dirPath) : fs.mkdirSync(dirPath);
-            }
-            if (!fs.existsSync(destReadmePath)) {
-                dryRun ? console.log("  --> Would create file README.md in " + dirPath) : fs.copyFileSync(filePath, destReadmePath);
-            } else {
-                dryRun ? console.log("  --> Would replace README.md in " + dirPath) : fs.copyFileSync(filePath, destReadmePath);
-            }
-            
+    const resolvedSrcReadmePaths = path.resolve(rootDir, srcReadmePaths);
+    glob(resolvedSrcReadmePaths, {realpath:true}, function(error, srcFiles) {
+
+        srcFiles.forEach((srcReadmePath) => {    
+            createDestReadme(srcReadmePath);
+            const srcDirPath = path.dirname(srcReadmePath);
+            const lastSrcDir = srcDirPath.split(path.sep).pop();
+            sidebarEntries.push(`en/packages/${lastSrcDir}/index`);
         });
 
+        updateSidebar();
+       
     });
 
 }
 
 /**
- * Copy all files
+ * Builds a new readme in ./docs/en/packages
+ * Creates and adds a docusaurus header to the new file
+ * Then appends the original readme from .docs/en/packages/[package-name]
  */
-copyReadmeFiles();
+function createDestReadme(srcReadmePath) {
+ 
+    const destReadmePath = srcReadmePath.replace(/(\bpackages\b)(?!.*\1)/, destDir);
+    const destDirPath = path.dirname(destReadmePath);
+    const srcDirPath = path.dirname(srcReadmePath);
+    const srcReadmeText = fs.readFileSync(srcReadmePath).toString();
+
+    var folderName = srcDirPath
+        .split(path.sep)
+        .pop();
+
+    var title = folderName
+        .replace(/-/g, ' ')
+        .replace(/fast /g, '')
+        .toLowerCase()
+        .split(' ')
+        .map((s) => s.charAt(0).toUpperCase() + s.substring(1))
+        .join(' ');
+
+    var docusaurusHeader = 
+        `---\n` + 
+        `id: index\n` + 
+        `title: FAST ${title}\n` + 
+        `sidebar_label: ${title}\n` +
+        `---\n\n`;
+
+    if (!fs.existsSync(destDirPath)) {
+        dryRun ? console.log(`...CREATE folder '${folderName}'`) : fs.mkdirSync(destDirPath);
+    }
+
+    if (dryRun) {
+
+        if (fs.existsSync(destReadmePath)) {
+            console.log(`...REPLACE readme.md in the '${folderName}' folder`);
+        } else {
+            console.log(`...ADD readme.md into the '${folderName}' folder`);
+        }
+
+    } else {
+        try {
+            fs.writeFileSync(destReadmePath, docusaurusHeader);
+            fs.appendFileSync(destReadmePath, srcReadmeText);
+            console.log('\x1b[32m%s\x1b[0m', `${destReadmePath} was succesfully updated!`);
+        } catch (err) {
+            console.log('\x1b[31m%s\x1b[0m', err);
+        }
+    }
+
+}
+
+/**
+ * Updates ./website/sidebars.json
+ */
+function updateSidebar() {
+
+    var sidebarJSONPath = path.resolve(rootDir, srcSidebar);
+    const sidebarText = fs.readFileSync(sidebarJSONPath).toString();
+    var sidebarJSON = JSON.parse(sidebarText);
+    sidebarJSON.docs.Packages = [];
+
+    sidebarEntries
+        .map((entry) => sidebarJSON.docs.Packages.push(entry))
+
+    if (dryRun) {
+        console.log("In website/sidebars.json, this script updates...\n" +
+            "...the Packages array with the filepath to each package's index file.");
+    } else {
+        fs.writeFile(sidebarJSONPath, JSON.stringify(sidebarJSON, null, 2), 'utf8', (err) => {
+            if (err) throw err;
+            console.log('\x1b[32m%s\x1b[0m', "./website/sidebar.json was succesfully updated!");
+        }); 
+    }
+
+}
+
+/**
+ * Run script
+ * Based off presence of --dry-run parameter
+ */
+copyReadmeFiles();

package.json

@@ -24,7 +24,9 @@
     "tslint:fix": "tslint -c ./tslint.json --fix 'build/**/*.ts'",
     "unit-tests": "jest --maxWorkers=4",
     "unit-tests:watch": "jest --watch",
-    "watch": "tsc -p ./tsconfig.json -w --preserveWatchOutput"
+    "watch": "tsc -p ./tsconfig.json -w --preserveWatchOutput",
+    "docs:dry-run": "node build/documentation/copy-package-readme.js --dry-run",
+    "docs:build": "node build/documentation/copy-package-readme.js"
   },
   "husky": {
     "hooks": {

website/sidebars.json

@@ -11,6 +11,7 @@
     ],
     "Packages": [
       "en/packages/fast-animation/index",
+      "en/packages/fast-application-utilities/index",
       "en/packages/fast-breakpoint-tracker-react/index",
       "en/packages/fast-browser-extensions/index",
       "en/packages/fast-colors/index",
@@ -26,16 +27,16 @@
       "en/packages/fast-form-generator-react/index",
       "en/packages/fast-glyphs-msft/index",
       "en/packages/fast-jest-snapshots-react/index",
-      "en/packages/fast-jss-manager/index",
       "en/packages/fast-jss-manager-angular/index",
       "en/packages/fast-jss-manager-react/index",
+      "en/packages/fast-jss-manager/index",
       "en/packages/fast-jss-utilities/index",
       "en/packages/fast-layouts-react/index",
       "en/packages/fast-markdown-msft-react/index",
       "en/packages/fast-permutator/index",
-      "en/packages/fast-sketch-library/index",
       "en/packages/fast-tslint-rules/index",
       "en/packages/fast-viewer-react/index",
-      "en/packages/fast-web-utilities/index"    ]
+      "en/packages/fast-web-utilities/index"
+    ]
   }
 }