Skip to content

Commit 4b6b224

Browse files
authored
Auto-generating links to re-exported Firestore types (#519)
1 parent 935b81b commit 4b6b224

File tree

4 files changed

+621
-60
lines changed

4 files changed

+621
-60
lines changed

docgen/content-sources/node/toc.yaml

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,6 @@ toc:
7777

7878
- title: "admin.firestore"
7979
path: /docs/reference/admin/node/admin.firestore
80-
section:
81-
- title: "FieldPath"
82-
path: /docs/reference/admin/node/admin.firestore.FieldPath
83-
- title: "FieldValue"
84-
path: /docs/reference/admin/node/admin.firestore.FieldValue
85-
- title: "GeoPoint"
86-
path: /docs/reference/admin/node/admin.firestore.GeoPoint
8780

8881
- title: "admin.instanceId"
8982
path: /docs/reference/admin/node/admin.instanceId

docgen/generate-docs.js

Lines changed: 74 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,11 @@
1616
*/
1717

1818
const { exec } = require('child-process-promise');
19-
const yargs = require('yargs');
2019
const fs = require('mz/fs');
20+
const jsdom = require('jsdom');
2121
const path = require('path');
22+
const readline = require('readline');
23+
const yargs = require('yargs');
2224
const yaml = require('js-yaml');
2325

2426
const repoPath = path.resolve(`${__dirname}/..`);
@@ -38,6 +40,17 @@ const contentPath = path.resolve(`${__dirname}/content-sources/node`);
3840
const tempHomePath = path.resolve(`${contentPath}/HOME_TEMP.md`);
3941
const devsitePath = `/docs/reference/admin/node/`;
4042

43+
const firestoreExcludes = ['v1', 'v1beta1', 'setLogFunction'];
44+
const firestoreHtmlPath = `${docPath}/admin.firestore.html`;
45+
const firestoreHeader = `<section class="tsd-panel-group tsd-member-group ">
46+
<h2>Type aliases</h2>
47+
<div class="tsd-panel">
48+
<p>Following types are defined in the <code>@google-cloud/firestore</code> package
49+
and re-exported from this namespace for convenience.</p>
50+
</div>
51+
<ul>`;
52+
const firestoreFooter = '\n </ul>\n</section>\n';
53+
4154
/**
4255
* Strips path prefix and returns only filename.
4356
* @param {string} path
@@ -107,7 +120,8 @@ function generateTempHomeMdFile(tocRaw, homeRaw) {
107120
let tocPageLines = [homeRaw, '# API Reference'];
108121
toc.forEach(group => {
109122
tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)})`);
110-
group.section.forEach(item => {
123+
const section = group.section || [];
124+
section.forEach(item => {
111125
tocPageLines.push(`- [${item.title}](${stripPath(item.path)}.html)`);
112126
});
113127
});
@@ -235,6 +249,63 @@ function fixAllLinks(htmlFiles) {
235249
return Promise.all(writePromises);
236250
}
237251

252+
/**
253+
* Updates the auto-generated Firestore API references page, by appending
254+
* the specified HTML content block.
255+
*
256+
* @param {string} contentBlock The HTML content block to be added to the Firestore docs.
257+
*/
258+
function updateFirestoreHtml(contentBlock) {
259+
const dom = new jsdom.JSDOM(fs.readFileSync(firestoreHtmlPath));
260+
const contentNode = dom.window.document.body.querySelector('.col-12');
261+
262+
const newSection = new jsdom.JSDOM(contentBlock);
263+
contentNode.appendChild(newSection.window.document.body.firstChild);
264+
fs.writeFileSync(firestoreHtmlPath, dom.window.document.documentElement.outerHTML);
265+
}
266+
267+
/**
268+
* Adds Firestore type aliases to the auto-generated API docs. These are the
269+
* types that are imported from the @google-cloud/firestore package, and
270+
* then re-exported from the admin.firestore namespace. Typedoc currently
271+
* does not handle these correctly, so we need this solution instead.
272+
*/
273+
function addFirestoreTypeAliases() {
274+
return new Promise((resolve, reject) => {
275+
const fileStream = fs.createReadStream(`${repoPath}/src/index.d.ts`);
276+
fileStream.on('error', (err) => {
277+
reject(err);
278+
});
279+
const lineReader = readline.createInterface({
280+
input: fileStream,
281+
});
282+
283+
let contentBlock = firestoreHeader;
284+
lineReader.on('line', (line) => {
285+
line = line.trim();
286+
if (line.startsWith('export import') && line.indexOf('_firestore.')) {
287+
const typeName = line.split(' ')[2];
288+
if (firestoreExcludes.indexOf(typeName) === -1) {
289+
contentBlock += `
290+
<li>
291+
<a href="https://cloud.google.com/nodejs/docs/reference/firestore/latest/${typeName}">${typeName}</a>
292+
</li>`;
293+
}
294+
}
295+
});
296+
297+
lineReader.on('close', () => {
298+
try {
299+
contentBlock += firestoreFooter;
300+
updateFirestoreHtml(contentBlock);
301+
resolve();
302+
} catch (err) {
303+
reject(err);
304+
}
305+
});
306+
});
307+
}
308+
238309
/**
239310
* Main document generation process.
240311
*
@@ -295,6 +366,7 @@ Promise.all([
295366
.then(fixAllLinks)
296367
// Add local variable include line to index.html (to access current SDK
297368
// version number).
369+
.then(addFirestoreTypeAliases)
298370
.then(() => {
299371
fs.readFile(`${docPath}/index.html`, 'utf8').then(data => {
300372
// String to include devsite local variables.

0 commit comments

Comments
 (0)