Exclude unwanted packages in docgen script (#6469)

Author: hsubox76

.gitignore

@@ -93,4 +93,5 @@ tsdoc-metadata.json
 
 # generated html docs
 docs-*/
-docs/
+docs/
+toc/

scripts/docgen/docgen.ts

@@ -37,19 +37,79 @@ https://github.com/firebase/firebase-js-sdk
 `;
 
 const tmpDir = `${projectRoot}/temp`;
+const EXCLUDED_PACKAGES = ['app-compat', 'util', 'rules-unit-testing'];
 
 yargs
-  .command('$0', 'generate standard reference docs', {}, _argv =>
-    generateDocs(/* forDevsite */ false)
+  .command(
+    '$0',
+    'generate standard reference docs',
+    {
+      skipBuild: {
+        type: 'boolean',
+        default: false
+      }
+    },
+    _argv => generateDocs(/* forDevsite */ false, _argv.skipBuild)
   )
-  .command('devsite', 'generate reference docs for devsite', {}, _argv =>
-    generateDocs(/* forDevsite */ true)
+  .command(
+    'devsite',
+    'generate reference docs for devsite',
+    {
+      skipBuild: {
+        type: 'boolean',
+        default: false
+      }
+    },
+    _argv => generateDocs(/* forDevsite */ true, _argv.skipBuild)
   )
+  .command('toc', 'generate devsite TOC', {}, _argv => generateToc())
+  .option('skipBuild', {
+    describe:
+      'Skip yarn build and api-report - only do this if you have already generated the most up to date .api.json files',
+    type: 'boolean'
+  })
   .demandCommand()
   .help().argv;
 
+async function generateToc() {
+  console.log(`Temporarily renaming excluded packages' json files.`);
+  for (const excludedPackage of EXCLUDED_PACKAGES) {
+    if (fs.existsSync(`${projectRoot}/temp/${excludedPackage}.api.json`)) {
+      fs.renameSync(
+        `${projectRoot}/temp/${excludedPackage}.api.json`,
+        `${projectRoot}/temp/${excludedPackage}.skip`
+      );
+    }
+  }
+  await spawn(
+    'yarn',
+    [
+      'api-documenter-devsite',
+      'toc',
+      '--input',
+      'temp',
+      '-p',
+      'docs/reference/js/v9',
+      '-j'
+    ],
+    { stdio: 'inherit' }
+  );
+  console.log(`Restoring excluded packages' json files.`);
+  for (const excludedPackage of EXCLUDED_PACKAGES) {
+    if (fs.existsSync(`${projectRoot}/temp/${excludedPackage}.skip`)) {
+      fs.renameSync(
+        `${projectRoot}/temp/${excludedPackage}.skip`,
+        `${projectRoot}/temp/${excludedPackage}.api.json`
+      );
+    }
+  }
+}
+
 // create *.api.json files
-async function generateDocs(forDevsite: boolean = false) {
+async function generateDocs(
+  forDevsite: boolean = false,
+  skipBuild: boolean = false
+) {
   const outputFolder = forDevsite ? 'docs-devsite' : 'docs';
   const command = forDevsite ? 'api-documenter-devsite' : 'api-documenter';
 
@@ -67,13 +127,15 @@ async function generateDocs(forDevsite: boolean = false) {
     authApiConfigModified
   );
 
-  await spawn('yarn', ['build'], {
-    stdio: 'inherit'
-  });
+  if (!skipBuild) {
+    await spawn('yarn', ['build'], {
+      stdio: 'inherit'
+    });
 
-  await spawn('yarn', ['api-report'], {
-    stdio: 'inherit'
-  });
+    await spawn('yarn', ['api-report'], {
+      stdio: 'inherit'
+    });
+  }
 
   // Restore original auth api-extractor.json contents.
   fs.writeFileSync(
@@ -136,7 +198,24 @@ async function generateDocs(forDevsite: boolean = false) {
     }
   }
 
-  moveRulesUnitTestingDocs(outputFolder, command);
+  await moveRulesUnitTestingDocs(outputFolder, command);
+  await removeExcludedDocs(outputFolder);
+}
+
+async function removeExcludedDocs(mainDocsFolder: string) {
+  console.log('Removing excluded docs from', EXCLUDED_PACKAGES.join(', '));
+  for (const excludedPackage of EXCLUDED_PACKAGES) {
+    const excludedMdFiles = await new Promise<string[]>(resolve =>
+      glob(`${mainDocsFolder}/${excludedPackage}.*`, (err, paths) => {
+        if (err) throw err;
+        resolve(paths);
+      })
+    );
+    console.log('glob pattern', `${mainDocsFolder}/${excludedPackage}.*`);
+    for (const excludedMdFile of excludedMdFiles) {
+      fs.unlinkSync(excludedMdFile);
+    }
+  }
 }
 
 // Create a docs-rut folder and move rules-unit-testing docs into it.
@@ -146,6 +225,8 @@ async function moveRulesUnitTestingDocs(
 ) {
   const rulesOutputFolder = `${projectRoot}/docs-rut`;
 
+  console.log('Moving RUT docs to their own folder:', rulesOutputFolder);
+
   if (!fs.existsSync(rulesOutputFolder)) {
     fs.mkdirSync(rulesOutputFolder);
   }
@@ -176,6 +257,5 @@ async function moveRulesUnitTestingDocs(
       `${jsReferencePath}/firestore`
     );
     fs.writeFileSync(destinationPath, alteredPathText);
-    fs.unlinkSync(sourcePath);
   }
 }