Modify doc generation script to also generate node reference docs (#1604)

Modify docgen script to generate node docs as well. Create npm scripts to generate js docs, or node docs, or both.

package.json

@@ -30,7 +30,9 @@
     "test:setup": "node tools/config.js",
     "pretest:saucelabs": "lerna run --parallel pretest",
     "test:saucelabs": "karma start config/karma.saucelabs.js --single-run",
-    "docgen": "node scripts/docgen/generate-docs.js"
+    "docgen:js": "node scripts/docgen/generate-docs.js --api js",
+    "docgen:node": "node scripts/docgen/generate-docs.js --api node",
+    "docgen": "npm run docgen:js; npm run docgen:node"
   },
   "repository": {
     "type": "git",

scripts/docgen/content-sources/js/toc.yaml

@@ -93,8 +93,6 @@ toc:
     path: /docs/reference/js/firebase.firestore.Query
   - title: "QueryDocumentSnapshot"
     path: /docs/reference/js/firebase.firestore.QueryDocumentSnapshot
-  - title: "QueryListenOptions"
-    path: /docs/reference/js/firebase.firestore.QueryListenOptions
   - title: "QuerySnapshot"
     path: /docs/reference/js/firebase.firestore.QuerySnapshot
   - title: "SetOptions"

scripts/docgen/content-sources/node/HOME.md

@@ -0,0 +1,12 @@
+# Firebase JavaScript SDK Reference For Node.js
+The Firebase JavaScript SDK implements the client-side libraries used by
+applications using Firebase services. This SDK is distributed via:
+
+- CDN (`<script src="https://www.gstatic.com/firebasejs/{{ web_sdk_version }}/firebase.js"></script>`)
+- [npm package](https://www.npmjs.com/package/firebase)
+- [Bower package](https://github.com/firebase/firebase-bower)
+
+To get started using Firebase, see
+[Add Firebase to your JavaScript Project](https://firebase.google.com/docs/web/setup).
+
+For source code, see the [Firebase JavaScript SDK Github repo](https://github.com/firebase/firebase-js-sdk).

scripts/docgen/content-sources/node/toc.yaml

@@ -0,0 +1,104 @@
+toc:
+- title: "firebase"
+  path: /docs/reference/node/firebase
+  section:
+  - title: "FirebaseError"
+    path: /docs/reference/node/firebase.FirebaseError
+
+- title: "firebase.app"
+  path: /docs/reference/node/firebase.app
+  section:
+  - title: "App"
+    path: /docs/reference/node/firebase.app.App
+
+- title: "firebase.auth"
+  path: /docs/reference/node/firebase.auth
+  section:
+  - title: "Auth"
+    path: /docs/reference/node/firebase.auth.Auth
+  - title: "ActionCodeInfo"
+    path: /docs/reference/node/firebase.auth.ActionCodeInfo
+  - title: "AuthCredential"
+    path: /docs/reference/node/firebase.auth.AuthCredential
+  - title: "AuthProvider"
+    path: /docs/reference/node/firebase.auth.AuthProvider
+  - title: "EmailAuthProvider"
+    path: /docs/reference/node/firebase.auth.EmailAuthProvider
+  - title: "Error"
+    path: /docs/reference/node/firebase.auth.Error
+  - title: "FacebookAuthProvider"
+    path: /docs/reference/node/firebase.auth.FacebookAuthProvider
+  - title: "GithubAuthProvider"
+    path: /docs/reference/node/firebase.auth.GithubAuthProvider
+  - title: "GoogleAuthProvider"
+    path: /docs/reference/node/firebase.auth.GoogleAuthProvider
+  - title: "TwitterAuthProvider"
+    path: /docs/reference/node/firebase.auth.TwitterAuthProvider
+  - title: "OAuthProvider"
+    path: /docs/reference/node/firebase.auth.OAuthProvider
+  - title: "SAMLAuthProvider"
+    path: /docs/reference/node/firebase.auth.SAMLAuthProvider
+  - title: "User"
+    path: /docs/reference/node/firebase.User
+  - title: "UserInfo"
+    path: /docs/reference/node/firebase.UserInfo
+
+- title: "firebase.database"
+  path: /docs/reference/node/firebase.database
+  section:
+  - title: "Database"
+    path: /docs/reference/node/firebase.database.Database
+  - title: "DataSnapshot"
+    path: /docs/reference/node/firebase.database.DataSnapshot
+  - title: "OnDisconnect"
+    path: /docs/reference/node/firebase.database.OnDisconnect
+  - title: "Query"
+    path: /docs/reference/node/firebase.database.Query
+  - title: "Reference"
+    path: /docs/reference/node/firebase.database.Reference
+  - title: "ServerValue"
+    path: /docs/reference/node/firebase.database.ServerValue
+  - title: "ThenableReference"
+    path: /docs/reference/node/firebase.database.ThenableReference
+
+- title: "firebase.firestore"
+  path: /docs/reference/node/firebase.firestore
+  section:
+  - title: "Blob"
+    path: /docs/reference/node/firebase.firestore.Blob
+  - title: "CollectionReference"
+    path: /docs/reference/node/firebase.firestore.CollectionReference
+  - title: "DocumentChange"
+    path: /docs/reference/node/firebase.firestore.DocumentChange
+  - title: "DocumentReference"
+    path: /docs/reference/node/firebase.firestore.DocumentReference
+  - title: "DocumentSnapshot"
+    path: /docs/reference/node/firebase.firestore.DocumentSnapshot
+  - title: "FieldPath"
+    path: /docs/reference/node/firebase.firestore.FieldPath
+  - title: "FieldValue"
+    path: /docs/reference/node/firebase.firestore.FieldValue
+  - title: "Firestore"
+    path: /docs/reference/node/firebase.firestore.Firestore
+  - title: "FirestoreError"
+    path: /docs/reference/node/firebase.firestore.FirestoreError
+  - title: "GeoPoint"
+    path: /docs/reference/node/firebase.firestore.GeoPoint
+  - title: "Query"
+    path: /docs/reference/node/firebase.firestore.Query
+  - title: "QueryDocumentSnapshot"
+    path: /docs/reference/node/firebase.firestore.QueryDocumentSnapshot
+  - title: "QuerySnapshot"
+    path: /docs/reference/node/firebase.firestore.QuerySnapshot
+  - title: "SetOptions"
+    path: /docs/reference/node/firebase.firestore.SetOptions
+  - title: "Settings"
+    path: /docs/reference/node/firebase.firestore.Settings
+  - title: "SnapshotMetadata"
+    path: /docs/reference/node/firebase.firestore.SnapshotMetadata
+  - title: "SnapshotOptions"
+    path: /docs/reference/node/firebase.firestore.SnapshotOptions
+  - title: "Transaction"
+    path: /docs/reference/node/firebase.firestore.Transaction
+  - title: "WriteBatch"
+    path: /docs/reference/node/firebase.firestore.WriteBatch

scripts/docgen/generate-docs.js

@@ -16,18 +16,32 @@
  */
 
 const { exec } = require('child-process-promise');
-const { argv } = require('yargs');
+const yargs = require('yargs');
 const fs = require('mz/fs');
 const path = require('path');
 const yaml = require('js-yaml');
 
 const repoPath = path.resolve(`${__dirname}/../..`);
-const docPath = path.resolve(`${__dirname}/html`);
-const sourceFile = argv.source
-  ? path.resolve(argv.source)
-  : `${repoPath}/packages/firebase/index.d.ts`;
-const tempHomePath = path.resolve(`${__dirname}/HOME_TEMP.md`);
-const devsitePath = '/docs/reference/js/';
+
+// Command-line options.
+const { api: apiType, source: sourceFile } = yargs
+  .option('api', {
+    default: 'js',
+    describe: 'api to generate docs for ("js" or "node")',
+    type: 'string'
+  })
+  .option('source', {
+    default: `${repoPath}/packages/firebase/index.d.ts`,
+    describe: 'Typescript source file(s)',
+    type: 'string'
+  })
+  .version(false)
+  .help().argv;
+
+const docPath = path.resolve(`${__dirname}/html/${apiType}`);
+const contentPath = path.resolve(`${__dirname}/content-sources/${apiType}`);
+const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`);
+const devsitePath = `/docs/reference/${apiType}/`;
 
 /**
  * Strips path prefix and returns only filename.
@@ -46,7 +60,7 @@ function stripPath(path) {
 function runTypedoc() {
   const command = `${repoPath}/node_modules/.bin/typedoc ${sourceFile} \
   --out ${docPath} \
-  --readme ${__dirname}/HOME_TEMP.md \
+  --readme ${tempHomePath} \
   --options ${__dirname}/typedoc.js \
   --theme ${__dirname}/theme`;
 
@@ -149,30 +163,42 @@ function checkForMissingFilesAndFixFilenameCase() {
 
 /**
  * Gets a list of html files in generated dir and checks if any are not
- * found in toc.yaml
+ * found in toc.yaml.
+ * Option to remove the file if not found (used for node docs).
  *
  * @param {Array} filenamesFromToc Filenames pulled from toc.yaml
+ * @param {boolean} shouldRemove Should just remove the file
  */
-function checkForUnlistedFiles(filenamesFromToc) {
+function checkForUnlistedFiles(filenamesFromToc, shouldRemove) {
   return fs.readdir(docPath).then(files => {
     const htmlFiles = files
       .filter(filename => filename.slice(-4) === 'html')
       .map(filename => filename.slice(0, -5));
+    const removePromises = [];
     htmlFiles.forEach(filename => {
-      // This is just a warning, it doesn't need to finish before
-      // the process continues.
       if (
         !filenamesFromToc.includes(filename) &&
         filename !== 'index' &&
         filename !== 'globals'
       ) {
-        console.warn(
-          `Unlisted file: ${filename} generated ` +
-            `but not listed in toc.yaml.`
-        );
+        if (shouldRemove) {
+          console.log(`REMOVING ${filename} - not listed in toc.yaml.`);
+          removePromises.push(() => fs.unlink(`${docPath}/${filename}`));
+        } else {
+          // This is just a warning, it doesn't need to finish before
+          // the process continues.
+          console.warn(
+            `Unlisted file: ${filename} generated ` +
+              `but not listed in toc.yaml.`
+          );
+        }
       }
     });
-    return htmlFiles;
+    if (shouldRemove) {
+      return Promise.all(removePromises).then(() => htmlFiles);
+    } else {
+      return htmlFiles;
+    }
   });
 }
 
@@ -223,8 +249,8 @@ function fixAllLinks(htmlFiles) {
  * 5) Check for mismatches between TOC list and generated file list.
  */
 Promise.all([
-  fs.readFile(`${__dirname}/toc.yaml`, 'utf8'),
-  fs.readFile(`${__dirname}/HOME.md`, 'utf8')
+  fs.readFile(`${contentPath}/toc.yaml`, 'utf8'),
+  fs.readFile(`${contentPath}/HOME.md`, 'utf8')
 ])
   // Read TOC and homepage text and assemble a homepage markdown file.
   // This file will be sourced by Typedoc to generate index.html.
@@ -258,8 +284,11 @@ Promise.all([
   // Not blocking.
   .then(checkForMissingFilesAndFixFilenameCase)
   // Check for files that exist but aren't listed in the TOC and warn.
-  // Not blocking.
-  .then(filenamesFromToc => checkForUnlistedFiles(filenamesFromToc))
+  // (If API is node, actually remove the file.)
+  // Removal is blocking, warnings aren't.
+  .then(filenamesFromToc =>
+    checkForUnlistedFiles(filenamesFromToc, apiType === 'node')
+  )
   // Write a _toc_autogenerated.yaml to record what files were created.
   .then(htmlFiles => writeGeneratedFileList(htmlFiles))
   // Correct the links in all the generated html files now that files have