16
16
*/
17
17
18
18
const { exec } = require ( 'child-process-promise' ) ;
19
- const yargs = require ( 'yargs' ) ;
20
19
const fs = require ( 'mz/fs' ) ;
20
+ const jsdom = require ( 'jsdom' ) ;
21
21
const path = require ( 'path' ) ;
22
+ const readline = require ( 'readline' ) ;
23
+ const yargs = require ( 'yargs' ) ;
22
24
const yaml = require ( 'js-yaml' ) ;
23
25
24
26
const repoPath = path . resolve ( `${ __dirname } /..` ) ;
@@ -38,6 +40,17 @@ const contentPath = path.resolve(`${__dirname}/content-sources/node`);
38
40
const tempHomePath = path . resolve ( `${ contentPath } /HOME_TEMP.md` ) ;
39
41
const devsitePath = `/docs/reference/admin/node/` ;
40
42
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
+
41
54
/**
42
55
* Strips path prefix and returns only filename.
43
56
* @param {string } path
@@ -107,7 +120,8 @@ function generateTempHomeMdFile(tocRaw, homeRaw) {
107
120
let tocPageLines = [ homeRaw , '# API Reference' ] ;
108
121
toc . forEach ( group => {
109
122
tocPageLines . push ( `\n## [${ group . title } ](${ stripPath ( group . path ) } )` ) ;
110
- group . section . forEach ( item => {
123
+ const section = group . section || [ ] ;
124
+ section . forEach ( item => {
111
125
tocPageLines . push ( `- [${ item . title } ](${ stripPath ( item . path ) } .html)` ) ;
112
126
} ) ;
113
127
} ) ;
@@ -235,6 +249,63 @@ function fixAllLinks(htmlFiles) {
235
249
return Promise . all ( writePromises ) ;
236
250
}
237
251
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
+
238
309
/**
239
310
* Main document generation process.
240
311
*
@@ -295,6 +366,7 @@ Promise.all([
295
366
. then ( fixAllLinks )
296
367
// Add local variable include line to index.html (to access current SDK
297
368
// version number).
369
+ . then ( addFirestoreTypeAliases )
298
370
. then ( ( ) => {
299
371
fs . readFile ( `${ docPath } /index.html` , 'utf8' ) . then ( data => {
300
372
// String to include devsite local variables.
0 commit comments