Skip to content

Commit 5d72c1b

Browse files
hiranya911hiranya911
authored
chore: Auto-generating typings from the source (#1072)
* chore: Removing ambient typing files (#1032) * chore: Removing ambient typing files * chore: Added some TODOs to keep track of WIP * chore: Added the credentials API signatures and exposed admin.credential (#1035) * chore: Added the credentials API signatures and exposed admin.credential * fix: Updated ServiceAccountCredential constructor signature * chore: Declared admin and admin.app namespaces (#1037) * chore: Added some TODOs to keep track of WIP * chore: Declared admin and admin.app namespaces * fix: Fixing an indentation issue * fix(rc): Exposed admin.remoteConfig namespace (#1038) * fix(fcm): Exposed admin.messaging namespace (#1039) * chore(iid): Exposed admin.instanceId namespace (#1046) * chore(iid): Exposed admin.instanceId namespace * fix: Fixing some bad indentation in comments * chore(rtdb): Exposed admin.database namespace (#1043) * chore(rules): Exposed admin.securiryRules namespace (#1050) * chore: Exposed admin.projectManagement namespace (#1054) * chore(auth): Exposed admin.auth namespace (#1053) * chore(auth): Exposed admin.auth namespace * fix(auth): Fixing unit tests for SAMLConfig * fix(auth): Removing more auth. prefixed direct references * fix(auth): Using CreateTenantRequest explicitly where appropriate * chore(ml): Exposed admin.machineLearning namespace (#1055) * chore(ml): Exposed admin.machineLearning namespace * fix(ml): Fixing some code formatting issues * chore: Exposed admin.storage and admin.firestore namespaces (#1056) * chore(ml): Exposed admin.machineLearning namespace * chore: Exposed admin.firestore and admin.storage namespaces * chore: Merged with upstream; Re-enabled build:tests CI task * chore: Using public API types in FirebaseNamespace impl (#1057) * chore: Updated TypeDoc workflow to generate API docs (#1060) * chore: Experimental typedoc pipeline for doc generation * chore: Adding RTDB type aliases to the API docs * Updated comments * Cleaned up the docgen script; Fixed a file name check warning * fix: Fixed cross links; Fixed a faulty regex replacement in links * fix: Fixing the remaining cross linkage errors * chore: Enabled quotes rule in eslint config (#1067) * chore: Enabled quotes rule in esline config * fix: Enabled avoidEscape option * fix: Fixed a typo in an error message
1 parent f0f720d commit 5d72c1b

File tree

97 files changed

+4435
-8427
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

97 files changed

+4435
-8427
lines changed

‎.eslintrc.js‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ module.exports = {
3333
// Disabled checks
3434
'@typescript-eslint/no-explicit-any': 0,
3535
'@typescript-eslint/no-use-before-define': 0,
36-
'@typescript-eslint/no-unused-vars': 0,
3736

3837
// Required checks
3938
'indent': ['error', 2],
@@ -45,7 +44,7 @@ module.exports = {
4544
'ignoreUrls': true
4645
}
4746
],
48-
"object-curly-spacing": [2, "always"],
47+
'object-curly-spacing': [2, 'always'],
4948
'@typescript-eslint/explicit-function-return-type': [
5049
'error',
5150
{
@@ -54,12 +53,8 @@ module.exports = {
5453
'allowHigherOrderFunctions': true
5554
}
5655
],
57-
'@typescript-eslint/no-unused-vars-experimental': 2,
58-
},
59-
// Required by the @typescript-eslint/no-unused-vars-experimental rule.
60-
// We use a separate tsconfig file for linting to reduce the time complexity of the operation.
61-
// See github.com/typescript-eslint/typescript-eslint/issues/1320
62-
parserOptions: {
63-
project: './tsconfig.eslint.json',
64-
},
56+
'no-unused-vars': 'off', // Must be disabled to enable the next rule
57+
'@typescript-eslint/no-unused-vars': ['error'],
58+
'quotes': ['error', 'single', {'avoidEscape': true}]
59+
}
6560
};

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

Lines changed: 18 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ toc:
1717
path: /docs/reference/admin/node/admin.app
1818
section:
1919
- title: "App"
20-
path: /docs/reference/admin/node/admin.app.App
20+
path: /docs/reference/admin/node/admin.app.App-1
2121

2222
- title: "admin.auth"
2323
path: /docs/reference/admin/node/admin.auth
2424
section:
2525
- title: "Auth"
26-
path: /docs/reference/admin/node/admin.auth.Auth
26+
path: /docs/reference/admin/node/admin.auth.Auth-1
2727
- title: "ActionCodeSettings"
2828
path: /docs/reference/admin/node/admin.auth.ActionCodeSettings
2929
- title: "AuthProviderConfig"
@@ -36,6 +36,8 @@ toc:
3636
path: /docs/reference/admin/node/admin.auth.CreatePhoneMultiFactorInfoRequest
3737
- title: "CreateRequest"
3838
path: /docs/reference/admin/node/admin.auth.CreateRequest
39+
- title: "EmailSignInProviderConfig"
40+
path: /docs/reference/admin/node/admin.auth.EmailSignInProviderConfig
3941
- title: "ListProviderConfigResults"
4042
path: /docs/reference/admin/node/admin.auth.ListProviderConfigResults
4143
- title: "ListTenantsResult"
@@ -115,25 +117,13 @@ toc:
115117
path: /docs/reference/admin/node/admin.credential
116118
section:
117119
- title: "Credential"
118-
path: /docs/reference/admin/node/admin.credential.Credential
120+
path: /docs/reference/admin/node/admin.credential.Credential-1
119121

120122
- title: "admin.database"
121123
path: /docs/reference/admin/node/admin.database
122124
section:
123125
- title: "Database"
124-
path: /docs/reference/admin/node/admin.database.Database
125-
- title: "DataSnapshot"
126-
path: /docs/reference/admin/node/admin.database.DataSnapshot
127-
- title: "OnDisconnect"
128-
path: /docs/reference/admin/node/admin.database.OnDisconnect
129-
- title: "Query"
130-
path: /docs/reference/admin/node/admin.database.Query
131-
- title: "Reference"
132-
path: /docs/reference/admin/node/admin.database.Reference
133-
- title: "ServerValue"
134-
path: /docs/reference/admin/node/admin.database.ServerValue
135-
- title: "ThenableReference"
136-
path: /docs/reference/admin/node/admin.database.ThenableReference
126+
path: /docs/reference/admin/node/admin.database.Database-1
137127

138128
- title: "admin.firestore"
139129
path: /docs/reference/admin/node/admin.firestore
@@ -142,7 +132,7 @@ toc:
142132
path: /docs/reference/admin/node/admin.instanceId
143133
section:
144134
- title: "InstanceId"
145-
path: /docs/reference/admin/node/admin.instanceId.InstanceId
135+
path: /docs/reference/admin/node/admin.instanceId.InstanceId-1
146136

147137
- title: "admin.machineLearning"
148138
path: /docs/reference/admin/node/admin.machineLearning
@@ -152,7 +142,7 @@ toc:
152142
- title: "ListModelsResult"
153143
path: /docs/reference/admin/node/admin.machineLearning.ListModelsResult
154144
- title: "MachineLearning"
155-
path: /docs/reference/admin/node/admin.machineLearning.MachineLearning
145+
path: /docs/reference/admin/node/admin.machineLearning.MachineLearning-1
156146
- title: "Model"
157147
path: /docs/reference/admin/node/admin.machineLearning.Model
158148
- title: "ModelOptionsBase"
@@ -167,12 +157,14 @@ toc:
167157
- title: "admin.messaging"
168158
path: /docs/reference/admin/node/admin.messaging
169159
section:
160+
- title: "BaseMessage"
161+
path: /docs/reference/admin/node/admin.messaging.BaseMessage
170162
- title: "TopicMessage"
171-
path: /docs/reference/admin/node/TopicMessage
163+
path: /docs/reference/admin/node/admin.messaging.TopicMessage
172164
- title: "TokenMessage"
173-
path: /docs/reference/admin/node/TokenMessage
165+
path: /docs/reference/admin/node/admin.messaging.TokenMessage
174166
- title: "ConditionMessage"
175-
path: /docs/reference/admin/node/ConditionMessage
167+
path: /docs/reference/admin/node/admin.messaging.ConditionMessage
176168
- title: "AndroidConfig"
177169
path: /docs/reference/admin/node/admin.messaging.AndroidConfig
178170
- title: "AndroidFcmOptions"
@@ -184,7 +176,7 @@ toc:
184176
- title: "LightSettings"
185177
path: /docs/reference/admin/node/admin.messaging.LightSettings
186178
- title: "Messaging"
187-
path: /docs/reference/admin/node/admin.messaging.Messaging
179+
path: /docs/reference/admin/node/admin.messaging.Messaging-1
188180
- title: "MessagingConditionResponse"
189181
path: /docs/reference/admin/node/admin.messaging.MessagingConditionResponse
190182
- title: "MessagingDeviceGroupResponse"
@@ -248,7 +240,7 @@ toc:
248240
- title: "IosAppMetadata"
249241
path: /docs/reference/admin/node/admin.projectManagement.IosAppMetadata
250242
- title: "ProjectManagement"
251-
path: /docs/reference/admin/node/admin.projectManagement.ProjectManagement
243+
path: /docs/reference/admin/node/admin.projectManagement.ProjectManagement-1
252244
- title: "ShaCertificate"
253245
path: /docs/reference/admin/node/admin.projectManagement.ShaCertificate
254246

@@ -264,19 +256,19 @@ toc:
264256
- title: "RulesetMetadataList"
265257
path: /docs/reference/admin/node/admin.securityRules.RulesetMetadataList
266258
- title: "SecurityRules"
267-
path: /docs/reference/admin/node/admin.securityRules.SecurityRules
259+
path: /docs/reference/admin/node/admin.securityRules.SecurityRules-1
268260

269261
- title: "admin.storage"
270262
path: /docs/reference/admin/node/admin.storage
271263
section:
272264
- title: "Storage"
273-
path: /docs/reference/admin/node/admin.storage.Storage
265+
path: /docs/reference/admin/node/admin.storage.Storage-1
274266

275267
- title: "admin.remoteConfig"
276268
path: /docs/reference/admin/node/admin.remoteConfig
277269
section:
278270
- title: "RemoteConfig"
279-
path: /docs/reference/admin/node/admin.remoteConfig.RemoteConfig
271+
path: /docs/reference/admin/node/admin.remoteConfig.RemoteConfig-1
280272
- title: "RemoteConfigTemplate"
281273
path: /docs/reference/admin/node/admin.remoteConfig.RemoteConfigTemplate
282274
- title: "RemoteConfigParameter"

‎docgen/generate-docs.js‎

Lines changed: 75 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,16 @@ const yaml = require('js-yaml');
2525

2626
const repoPath = path.resolve(`${__dirname}/..`);
2727

28+
const defaultSources = [
29+
`${repoPath}/lib/firebase-namespace.d.ts`,
30+
`${repoPath}/lib/firebase-namespace-api.d.ts`,
31+
`${repoPath}/lib/**/*.d.ts`,
32+
];
33+
2834
// Command-line options.
2935
const { source: sourceFile } = yargs
3036
.option('source', {
31-
default: `${repoPath}/src/*.d.ts`,
37+
default: defaultSources.join(' '),
3238
describe: 'Typescript source file(s)',
3339
type: 'string'
3440
})
@@ -51,6 +57,17 @@ const firestoreHeader = `<section class="tsd-panel-group tsd-member-group ">
5157
<ul>`;
5258
const firestoreFooter = '\n </ul>\n</section>\n';
5359

60+
const databaseExcludes = ['enableLogging'];
61+
const databaseHtmlPath = `${docPath}/admin.database.html`;
62+
const databaseHeader = `<section class="tsd-panel-group tsd-member-group ">
63+
<h2>Type aliases</h2>
64+
<div class="tsd-panel">
65+
<p>Following types are defined in the <code>@firebase/database</code> package
66+
and re-exported from this namespace for convenience.</p>
67+
</div>
68+
<ul>`;
69+
const databaseFooter = '\n </ul>\n</section>\n';
70+
5471
/**
5572
* Strips path prefix and returns only filename.
5673
* @param {string} path
@@ -99,7 +116,7 @@ function fixLinks(file) {
99116
.replace(/(modules|interfaces|classes|enums)\//g, '');
100117
let caseFixedLinks = flattenedLinks;
101118
for (const lower in lowerToUpperLookup) {
102-
const re = new RegExp(lower, 'g');
119+
const re = new RegExp('\\b' + lower, 'g');
103120
caseFixedLinks = caseFixedLinks.replace(re, lowerToUpperLookup[lower]);
104121
}
105122
return fs.writeFile(file, caseFixedLinks);
@@ -119,7 +136,7 @@ function generateTempHomeMdFile(tocRaw, homeRaw) {
119136
const { toc } = yaml.safeLoad(tocRaw);
120137
let tocPageLines = [homeRaw, '# API Reference'];
121138
toc.forEach(group => {
122-
tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)})`);
139+
tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)}.html)`);
123140
const section = group.section || [];
124141
section.forEach(item => {
125142
tocPageLines.push(`- [${item.title}](${stripPath(item.path)}.html)`);
@@ -150,13 +167,13 @@ function checkForMissingFilesAndFixFilenameCase() {
150167
// Preferred filename for devsite should be capitalized and taken from
151168
// toc.yaml.
152169
const tocFilePath = `${docPath}/${filename}.html`;
153-
// Generated filename from Typedoc will be lowercase.
154-
const generatedFilePath = `${docPath}/${filename.toLowerCase()}.html`;
170+
// Generated filename from Typedoc will be lowercase and won't have the admin prefix.
171+
const generatedFilePath = `${docPath}/${filename.toLowerCase().replace('admin.', '')}.html`;
155172
return fs.exists(generatedFilePath).then(exists => {
156173
if (exists) {
157174
// Store in a lookup table for link fixing.
158175
lowerToUpperLookup[
159-
`${filename.toLowerCase()}.html`
176+
`${filename.toLowerCase().replace('admin.', '')}.html`
160177
] = `${filename}.html`;
161178
return fs.rename(generatedFilePath, tocFilePath);
162179
} else {
@@ -167,6 +184,7 @@ function checkForMissingFilesAndFixFilenameCase() {
167184
}
168185
});
169186
});
187+
170188
return Promise.all(fileCheckPromises).then(() => filenames);
171189
}
172190

@@ -253,15 +271,16 @@ function fixAllLinks(htmlFiles) {
253271
* Updates the auto-generated Firestore API references page, by appending
254272
* the specified HTML content block.
255273
*
274+
* @param {string} htmlPath Path of the HTML file to update.
256275
* @param {string} contentBlock The HTML content block to be added to the Firestore docs.
257276
*/
258-
function updateFirestoreHtml(contentBlock) {
259-
const dom = new jsdom.JSDOM(fs.readFileSync(firestoreHtmlPath));
277+
function updateHtml(htmlPath, contentBlock) {
278+
const dom = new jsdom.JSDOM(fs.readFileSync(htmlPath));
260279
const contentNode = dom.window.document.body.querySelector('.col-12');
261280

262281
const newSection = new jsdom.JSDOM(contentBlock);
263282
contentNode.appendChild(newSection.window.document.body.firstChild);
264-
fs.writeFileSync(firestoreHtmlPath, dom.window.document.documentElement.outerHTML);
283+
fs.writeFileSync(htmlPath, dom.window.document.documentElement.outerHTML);
265284
}
266285

267286
/**
@@ -272,7 +291,7 @@ function updateFirestoreHtml(contentBlock) {
272291
*/
273292
function addFirestoreTypeAliases() {
274293
return new Promise((resolve, reject) => {
275-
const fileStream = fs.createReadStream(`${repoPath}/src/index.d.ts`);
294+
const fileStream = fs.createReadStream(`${repoPath}/lib/firestore/index.d.ts`);
276295
fileStream.on('error', (err) => {
277296
reject(err);
278297
});
@@ -297,7 +316,49 @@ function addFirestoreTypeAliases() {
297316
lineReader.on('close', () => {
298317
try {
299318
contentBlock += firestoreFooter;
300-
updateFirestoreHtml(contentBlock);
319+
updateHtml(firestoreHtmlPath, contentBlock);
320+
resolve();
321+
} catch (err) {
322+
reject(err);
323+
}
324+
});
325+
});
326+
}
327+
328+
/**
329+
* Adds RTDB type aliases to the auto-generated API docs. These are the
330+
* types that are imported from the @firebase/database package, and
331+
* then re-exported from the admin.database namespace. Typedoc currently
332+
* does not handle these correctly, so we need this solution instead.
333+
*/
334+
function addDatabaseTypeAliases() {
335+
return new Promise((resolve, reject) => {
336+
const fileStream = fs.createReadStream(`${repoPath}/lib/database/index.d.ts`);
337+
fileStream.on('error', (err) => {
338+
reject(err);
339+
});
340+
const lineReader = readline.createInterface({
341+
input: fileStream,
342+
});
343+
344+
let contentBlock = databaseHeader;
345+
lineReader.on('line', (line) => {
346+
line = line.trim();
347+
if (line.startsWith('export import') && line.indexOf('rtdb.') >= 0) {
348+
const typeName = line.split(' ')[2];
349+
if (databaseExcludes.indexOf(typeName) === -1) {
350+
contentBlock += `
351+
<li>
352+
<a href="/docs/reference/js/firebase.database.${typeName}.html">${typeName}</a>
353+
</li>`;
354+
}
355+
}
356+
});
357+
358+
lineReader.on('close', () => {
359+
try {
360+
contentBlock += databaseFooter;
361+
updateHtml(databaseHtmlPath, contentBlock);
301362
resolve();
302363
} catch (err) {
303364
reject(err);
@@ -349,6 +410,8 @@ Promise.all([
349410
moveFilesToRoot('enums'),
350411
]);
351412
})
413+
// Rename the globals file to be the top-level admin doc.
414+
.then(() => fs.rename(`${docPath}/globals.html`, `${docPath}/admin.html`))
352415
// Check for files listed in TOC that are missing and warn if so.
353416
// Not blocking.
354417
.then(checkForMissingFilesAndFixFilenameCase)
@@ -366,6 +429,7 @@ Promise.all([
366429
// Add local variable include line to index.html (to access current SDK
367430
// version number).
368431
.then(addFirestoreTypeAliases)
432+
.then(addDatabaseTypeAliases)
369433
.then(() => {
370434
fs.readFile(`${docPath}/index.html`, 'utf8').then(data => {
371435
// String to include devsite local variables.

0 commit comments

Comments
 (0)