From 41b0e40c34897129704f55a9110b627f3d521255 Mon Sep 17 00:00:00 2001 From: Erik Macik Date: Tue, 6 Aug 2019 14:40:13 -0700 Subject: [PATCH 1/7] First version of addTypeAliasLinks that will scan TypeDoc HTML output and insert links to external library documentation. --- docgen/generate-docs.js | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 299250e64..1041d8383 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -39,6 +39,9 @@ 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 { JSDOM } = jsdom; + /** * Strips path prefix and returns only filename. * @param {string} path @@ -103,6 +106,8 @@ function renameFiles() { */ function fixLinks(file) { return fs.readFile(file, 'utf8').then(data => { + console.log(file); + 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); + const fileTags = htmlDom.window.document.querySelectorAll(".tsd-signature-type"); + fileTags.forEach(tag => { + for (const type of typeMap.keys()) { + const lastTypeOccurrence = tag.textContent.lastIndexOf(type); + + // Helps to prevent matching similar types, like 'UserRecord' and 'UserRecordMetadata'. + if (lastTypeOccurrence >= 0 && lastTypeOccurrence + type.length == tag.textContent.length) { + console.log(' Found the '+type+' type! Adding link.'); + + // Add the corresponding document link to this type + const linkChild = htmlDom.window.document.createElement('a'); + linkChild.setAttribute('href', typeMap.get(type)); + linkChild.textContent = tag.textContent; + tag.textContent = null; + tag.appendChild(linkChild); + } + } + }); + return htmlDom.serialize(); +} + let tocText = ''; /** @@ -271,6 +305,12 @@ function fixAllLinks(htmlFiles) { * links as needed. * 5) Check for mismatches between TOC list and generated file list. */ + +var typeMap = new Map(); +typeMap.set('DocumentSnapshot', `https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html`); +typeMap.set('UserRecord', 'https://firebase.google.com/docs/reference/functions/functions.auth.UserRecord.html'); +typeMap.set('UserInfo', 'https://firebase.google.com/docs/reference/functions/functions.auth.UserInfo.html'); + Promise.all([ fs.readFile(`${contentPath}/toc.yaml`, 'utf8'), fs.readFile(`${contentPath}/HOME.md`, 'utf8') From 2fda3c328c0f08323ac81a365f199e0bfcac8ddc Mon Sep 17 00:00:00 2001 From: Erik Macik Date: Mon, 12 Aug 2019 15:23:02 -0700 Subject: [PATCH 2/7] Updated link for UserRecord and UserInfo --- docgen/generate-docs.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 1041d8383..cf29bcdcc 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -308,8 +308,8 @@ function fixAllLinks(htmlFiles) { var typeMap = new Map(); typeMap.set('DocumentSnapshot', `https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html`); -typeMap.set('UserRecord', 'https://firebase.google.com/docs/reference/functions/functions.auth.UserRecord.html'); -typeMap.set('UserInfo', 'https://firebase.google.com/docs/reference/functions/functions.auth.UserInfo.html'); +typeMap.set('UserRecord', 'https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html'); +typeMap.set('UserInfo', 'https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html'); Promise.all([ fs.readFile(`${contentPath}/toc.yaml`, 'utf8'), From cab295e0fc14b544a5118a601fd844b7c0a1e2f9 Mon Sep 17 00:00:00 2001 From: Erik Macik Date: Wed, 14 Aug 2019 15:25:49 -0700 Subject: [PATCH 3/7] 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. --- docgen/generate-docs.js | 22 +++++++++++++--------- docgen/type-aliases.json | 5 +++++ 2 files changed, 18 insertions(+), 9 deletions(-) create mode 100644 docgen/type-aliases.json diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index cf29bcdcc..3a7658fa4 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -39,8 +39,7 @@ 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 { JSDOM } = jsdom; +const { JSDOM } = require("jsdom"); /** * Strips path prefix and returns only filename. @@ -106,7 +105,6 @@ function renameFiles() { */ function fixLinks(file) { return fs.readFile(file, 'utf8').then(data => { - console.log(file); data = addTypeAliasLinks(data); const flattenedLinks = data .replace(/\.\.\//g, '') @@ -134,9 +132,9 @@ function addTypeAliasLinks(data) { for (const type of typeMap.keys()) { const lastTypeOccurrence = tag.textContent.lastIndexOf(type); - // Helps to prevent matching similar types, like 'UserRecord' and 'UserRecordMetadata'. + // Helps to prevent matching similar types, like `UserRecord` and `UserRecordMetadata`. if (lastTypeOccurrence >= 0 && lastTypeOccurrence + type.length == tag.textContent.length) { - console.log(' Found the '+type+' type! Adding link.'); + console.log('Adding link to '+type); // Add the corresponding document link to this type const linkChild = htmlDom.window.document.createElement('a'); @@ -305,12 +303,18 @@ function fixAllLinks(htmlFiles) { * links as needed. * 5) Check for mismatches between TOC list and generated file list. */ - var typeMap = new Map(); -typeMap.set('DocumentSnapshot', `https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html`); -typeMap.set('UserRecord', 'https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html'); -typeMap.set('UserInfo', 'https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html'); +fs.readFile('./type-aliases.json', (err, jsonString) => { + if (err) { + console.log('Error: type-aliases.json not found in this directory. Unable to link to external library documentation.'); + return; + } + typeJson = JSON.parse(jsonString); + typeJson.forEach(alias => { + typeMap.set(alias.type, alias.link); + }); +}); Promise.all([ fs.readFile(`${contentPath}/toc.yaml`, 'utf8'), fs.readFile(`${contentPath}/HOME.md`, 'utf8') diff --git a/docgen/type-aliases.json b/docgen/type-aliases.json new file mode 100644 index 000000000..8ff0cd4b5 --- /dev/null +++ b/docgen/type-aliases.json @@ -0,0 +1,5 @@ +[ + { "type": "DocumentSnapshot", "link": "https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html" }, + { "type": "UserRecord", "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html" }, + { "type": "UserInfo", "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html" } +] \ No newline at end of file From 97e42b01c52aa47775638184e6db724f7d114f7f Mon Sep 17 00:00:00 2001 From: Erik Macik Date: Wed, 14 Aug 2019 15:35:52 -0700 Subject: [PATCH 4/7] Ran npm run format:fix --- docgen/type-aliases.json | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docgen/type-aliases.json b/docgen/type-aliases.json index 8ff0cd4b5..d1faa03f3 100644 --- a/docgen/type-aliases.json +++ b/docgen/type-aliases.json @@ -1,5 +1,14 @@ [ - { "type": "DocumentSnapshot", "link": "https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html" }, - { "type": "UserRecord", "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html" }, - { "type": "UserInfo", "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html" } -] \ No newline at end of file + { + "type": "DocumentSnapshot", + "link": "https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html" + }, + { + "type": "UserRecord", + "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html" + }, + { + "type": "UserInfo", + "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html" + } +] From 852e839a7a722986bd07c18097153c39ee5da953 Mon Sep 17 00:00:00 2001 From: Erik Macik Date: Wed, 14 Aug 2019 16:35:56 -0700 Subject: [PATCH 5/7] 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. --- docgen/generate-docs.js | 28 +++++++--------------------- docgen/type-aliases.json | 19 +++++-------------- 2 files changed, 12 insertions(+), 35 deletions(-) diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 3a7658fa4..676393e53 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -41,6 +41,8 @@ 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 @@ -129,22 +131,18 @@ function addTypeAliasLinks(data) { const htmlDom = new JSDOM(data); const fileTags = htmlDom.window.document.querySelectorAll(".tsd-signature-type"); fileTags.forEach(tag => { - for (const type of typeMap.keys()) { - const lastTypeOccurrence = tag.textContent.lastIndexOf(type); - - // Helps to prevent matching similar types, like `UserRecord` and `UserRecordMetadata`. - if (lastTypeOccurrence >= 0 && lastTypeOccurrence + type.length == tag.textContent.length) { - console.log('Adding link to '+type); + 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', typeMap.get(type)); + linkChild.setAttribute('href', mapping); linkChild.textContent = tag.textContent; tag.textContent = null; tag.appendChild(linkChild); } - } - }); + }); return htmlDom.serialize(); } @@ -303,18 +301,6 @@ function fixAllLinks(htmlFiles) { * links as needed. * 5) Check for mismatches between TOC list and generated file list. */ -var typeMap = new Map(); -fs.readFile('./type-aliases.json', (err, jsonString) => { - if (err) { - console.log('Error: type-aliases.json not found in this directory. Unable to link to external library documentation.'); - return; - } - - typeJson = JSON.parse(jsonString); - typeJson.forEach(alias => { - typeMap.set(alias.type, alias.link); - }); -}); Promise.all([ fs.readFile(`${contentPath}/toc.yaml`, 'utf8'), fs.readFile(`${contentPath}/HOME.md`, 'utf8') diff --git a/docgen/type-aliases.json b/docgen/type-aliases.json index d1faa03f3..240c50269 100644 --- a/docgen/type-aliases.json +++ b/docgen/type-aliases.json @@ -1,14 +1,5 @@ -[ - { - "type": "DocumentSnapshot", - "link": "https://googleapis.dev/nodejs/firestore/latest/DocumentSnapshot.html" - }, - { - "type": "UserRecord", - "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserRecord.html" - }, - { - "type": "UserInfo", - "link": "https://firebase.google.com/docs/reference/admin/node/admin.auth.UserInfo.html" - } -] +{ + "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" +} From 875939e8e0df182b476d498771b7726b79978a46 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Wed, 23 Oct 2019 15:22:12 -0700 Subject: [PATCH 6/7] Adding comment as requested by thechenky. --- docgen/generate-docs.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index 676393e53..01275ae2d 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -129,6 +129,10 @@ function fixLinks(file) { */ 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]; From 56001d051d7bd553ec32448ee981ac66fe68c5a9 Mon Sep 17 00:00:00 2001 From: Eric Gilmore Date: Thu, 24 Oct 2019 11:16:12 -0700 Subject: [PATCH 7/7] Updating package.json to include JSDom module required by doc generation script. --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 70edbc1ab..b9d7e31fc 100644 --- a/package.json +++ b/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",