diff --git a/build/documentation/copy-package-readme.js b/build/documentation/copy-package-readme.js index 12924e214..2f99e6d9f 100644 --- a/build/documentation/copy-package-readme.js +++ b/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(); \ No newline at end of file diff --git a/package.json b/package.json index f01a846df..cec3e1dbe 100644 --- a/package.json +++ b/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": { diff --git a/website/sidebars.json b/website/sidebars.json index 6dca79b27..4a0be8bc0 100644 --- a/website/sidebars.json +++ b/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" + ] } } \ No newline at end of file