Fix docgen to skip unwanted packages

Author: hsubox76

scripts/docgen/docgen.ts

@@ -37,19 +37,69 @@ 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 +117,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 +188,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 +215,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 +247,5 @@ async function moveRulesUnitTestingDocs(
       `${jsReferencePath}/firestore`
     );
     fs.writeFileSync(destinationPath, alteredPathText);
-    fs.unlinkSync(sourcePath);
   }
 }

toc/toc.yaml

@@ -11,6 +11,8 @@ toc:
         path: docs/reference/js/v9/analytics.analyticscalloptions.md
       - title: AnalyticsSettings
         path: docs/reference/js/v9/analytics.analyticssettings.md
+      - title: ConsentSettings
+        path: docs/reference/js/v9/analytics.consentsettings.md
       - title: ControlParams
         path: docs/reference/js/v9/analytics.controlparams.md
       - title: CustomParams
@@ -32,8 +34,6 @@ toc:
         path: docs/reference/js/v9/app.firebaseapp.md
       - title: FirebaseAppSettings
         path: docs/reference/js/v9/app.firebaseappsettings.md
-      - title: FirebaseError
-        path: docs/reference/js/v9/app.firebaseerror.md
       - title: FirebaseOptions
         path: docs/reference/js/v9/app.firebaseoptions.md
   - title: app-check
@@ -55,17 +55,6 @@ toc:
         path: docs/reference/js/v9/app-check.recaptchaenterpriseprovider.md
       - title: ReCaptchaV3Provider
         path: docs/reference/js/v9/app-check.recaptchav3provider.md
-  - title: app-compat
-    path: docs/reference/js/v9/app-compat.md
-    section:
-      - title: _FirebaseNamespace
-        path: docs/reference/js/v9/app-compat._firebasenamespace.md
-      - title: _FirebaseService
-        path: docs/reference/js/v9/app-compat._firebaseservice.md
-      - title: FirebaseApp
-        path: docs/reference/js/v9/app-compat.firebaseapp.md
-      - title: FirebaseNamespace
-        path: docs/reference/js/v9/app-compat.firebasenamespace.md
   - title: auth
     path: docs/reference/js/v9/auth.md
     section:
@@ -354,17 +343,6 @@ toc:
         path: docs/reference/js/v9/remote-config.remoteconfigsettings.md
       - title: Value
         path: docs/reference/js/v9/remote-config.value.md
-  - title: rules-unit-testing
-    path: docs/reference/js/v9/rules-unit-testing.md
-    section:
-      - title: HostAndPort
-        path: docs/reference/js/v9/rules-unit-testing.hostandport.md
-      - title: RulesTestContext
-        path: docs/reference/js/v9/rules-unit-testing.rulestestcontext.md
-      - title: RulesTestEnvironment
-        path: docs/reference/js/v9/rules-unit-testing.rulestestenvironment.md
-      - title: TestEnvironmentConfig
-        path: docs/reference/js/v9/rules-unit-testing.testenvironmentconfig.md
   - title: storage
     path: docs/reference/js/v9/storage.md
     section:
@@ -392,26 +370,3 @@ toc:
         path: docs/reference/js/v9/storage.uploadtask.md
       - title: UploadTaskSnapshot
         path: docs/reference/js/v9/storage.uploadtasksnapshot.md
-  - title: util
-    path: docs/reference/js/v9/util.md
-    section:
-      - title: Compat
-        path: docs/reference/js/v9/util.compat.md
-      - title: Deferred
-        path: docs/reference/js/v9/util.deferred.md
-      - title: ErrorData
-        path: docs/reference/js/v9/util.errordata.md
-      - title: ErrorFactory
-        path: docs/reference/js/v9/util.errorfactory.md
-      - title: FirebaseError
-        path: docs/reference/js/v9/util.firebaseerror.md
-      - title: Observable
-        path: docs/reference/js/v9/util.observable.md
-      - title: Observer
-        path: docs/reference/js/v9/util.observer.md
-      - title: Sha1
-        path: docs/reference/js/v9/util.sha1.md
-      - title: StringLike
-        path: docs/reference/js/v9/util.stringlike.md
-      - title: Subscribe
-        path: docs/reference/js/v9/util.subscribe.md