Linking to external types - docgen (#549)

* First version of addTypeAliasLinks that will scan TypeDoc HTML output and insert links to external library documentation.

* Updated link for UserRecord and UserInfo

* Resolving a few of Hiranya's comments. Removing unecessary debugging console log, JSDOM is now imported with one line, and Map of types and links is now created from a JSON file,  Still need to resolve a couple of Hiranya's comments.

* Ran npm run format:fix

* Resolving more of Hiranya's comments. Loading JSON file uses 'require' rather than 'read file'. JSON file is now simpler. Script only replaces fully qualified names rather than aliases in document.

* Adding comment as requested by thechenky.

* Updating package.json to include JSDom module required by doc generation script.

Author: esmacik

docgen/generate-docs.js

@@ -39,6 +39,10 @@ const contentPath = path.resolve(`${__dirname}/content-sources`);
 const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`);
 const devsitePath = `/docs/reference/functions/`;
 
+const { JSDOM } = require("jsdom");
+
+const typeMap = require('./type-aliases.json');
+
 /**
  * Strips path prefix and returns only filename.
  * @param {string} path
@@ -103,6 +107,7 @@ function renameFiles() {
  */
 function fixLinks(file) {
   return fs.readFile(file, 'utf8').then(data => {
+    data = addTypeAliasLinks(data);
     const flattenedLinks = data
       .replace(/\.\.\//g, '')
       .replace(/(modules|interfaces|classes)\//g, '')
@@ -116,6 +121,35 @@ function fixLinks(file) {
   });
 }
 
+/** 
+ * Adds links to external documentation for type aliases that
+ * reference an external library.
+ * 
+ * @param data File data to add external library links to.
+ */
+function addTypeAliasLinks(data) {
+  const htmlDom = new JSDOM(data);
+  /**
+   * Select .tsd-signature-type because all potential external
+   * links will have this identifier.
+   */
+  const fileTags = htmlDom.window.document.querySelectorAll(".tsd-signature-type");
+  fileTags.forEach(tag => {
+    const mapping = typeMap[tag.textContent];
+      if (mapping) {
+        console.log('Adding link to '+tag.textContent+" documentation.");
+        
+        // Add the corresponding document link to this type
+        const linkChild = htmlDom.window.document.createElement('a');
+        linkChild.setAttribute('href', mapping);
+        linkChild.textContent = tag.textContent;
+        tag.textContent = null;
+        tag.appendChild(linkChild);
+      }
+    });
+  return htmlDom.serialize();
+}
+
 let tocText = '';
 
 /**

docgen/type-aliases.json

@@ -0,0 +1,5 @@
+{
+  "firebase.firestore.DocumentSnapshot": "https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html",
+  "firebase.auth.UserRecord": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html",
+  "firebase.auth.UserInfo": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html"
+}

package.json

@@ -58,6 +58,7 @@
     "firebase-admin": "^8.2.0",
     "istanbul": "^0.4.5",
     "js-yaml": "^3.13.1",
+    "jsdom": "^15.2.0",
     "mocha": "^6.1.4",
     "mock-require": "^3.0.3",
     "mz": "^2.7.0",