diff --git a/.gitignore b/.gitignore index ba3cdeec5..b5a890408 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ node_modules npm-debug.log typings yarn.lock +.DS_Store diff --git a/docgen/content-sources/toc.yaml b/docgen/content-sources/toc.yaml index e970fc80c..ac430151b 100644 --- a/docgen/content-sources/toc.yaml +++ b/docgen/content-sources/toc.yaml @@ -1,148 +1,148 @@ toc: - title: 'functions' - path: /docs/reference/functions/cloud_functions_.html + path: /docs/reference/functions/v1_cloud_functions_.html section: - title: 'CloudFunction' - path: /docs/reference/functions/cloud_functions_.html#cloudfunction + path: /docs/reference/functions/v1_cloud_functions_.html#cloudfunction - title: 'HttpsFunction' - path: /docs/reference/functions/cloud_functions_.html#httpsfunction + path: /docs/reference/functions/v1_cloud_functions_.html#httpsfunction - title: 'EventContext' - path: /docs/reference/functions/cloud_functions_.eventcontext.html + path: /docs/reference/functions/v1_cloud_functions_.eventcontext.html - title: 'FunctionBuilder' - path: /docs/reference/functions/function_builder_.functionbuilder.html + path: /docs/reference/functions/v1_function_builder_.functionbuilder.html - title: 'Change' - path: /docs/reference/functions/cloud_functions_.change.html + path: /docs/reference/functions/v1_cloud_functions_.change.html - title: 'ChangeJson' - path: /docs/reference/functions/cloud_functions_.changejson.html + path: /docs/reference/functions/v1_cloud_functions_.changejson.html - title: 'functions.config' - path: /docs/reference/functions/config_.html + path: /docs/reference/functions/v1_config_.html section: - title: 'Config' - path: /docs/reference/functions/config_.config.html + path: /docs/reference/functions/v1_config_.config.html - title: 'config.Config' - path: /docs/reference/functions/config_.config.config.html + path: /docs/reference/functions/v1_config_.config.config.html - title: 'functions.function-configuration' - path: /docs/reference/functions/function_configuration_.html + path: /docs/reference/functions/v1_function_configuration_.html section: - title: 'config.DeploymentOptions' - path: /docs/reference/functions/function_configuration_.deploymentoptions.html + path: /docs/reference/functions/v1_function_configuration_.deploymentoptions.html - title: 'config.FailurePolicy' - path: /docs/reference/functions/function_configuration_.failurepolicy.html + path: /docs/reference/functions/v1_function_configuration_.failurepolicy.html - title: 'config.RuntimeOptions' - path: /docs/reference/functions/function_configuration_.runtimeoptions.html + path: /docs/reference/functions/v1_function_configuration_.runtimeoptions.html - title: 'config.Schedule' - path: /docs/reference/functions/function_configuration_.schedule.html + path: /docs/reference/functions/v1_function_configuration_.schedule.html - title: 'config.ScheduleRetryConfig' - path: /docs/reference/functions/function_configuration_.scheduleretryconfig.html + path: /docs/reference/functions/v1_function_configuration_.scheduleretryconfig.html - title: 'functions.analytics' - path: /docs/reference/functions/providers_analytics_.html + path: /docs/reference/functions/v1_providers_analytics_.html section: - title: 'AnalyticsEvent' - path: /docs/reference/functions/providers_analytics_.analyticsevent.html + path: /docs/reference/functions/v1_providers_analytics_.analyticsevent.html - title: 'AnalyticsEventBuilder' - path: /docs/reference/functions/providers_analytics_.analyticseventbuilder.html + path: /docs/reference/functions/v1_providers_analytics_.analyticseventbuilder.html - title: 'AppInfo' - path: /docs/reference/functions/providers_analytics_.appinfo.html + path: /docs/reference/functions/v1_providers_analytics_.appinfo.html - title: 'DeviceInfo' - path: /docs/reference/functions/providers_analytics_.deviceinfo.html + path: /docs/reference/functions/v1_providers_analytics_.deviceinfo.html - title: 'ExportBundleInfo' - path: /docs/reference/functions/providers_analytics_.exportbundleinfo.html + path: /docs/reference/functions/v1_providers_analytics_.exportbundleinfo.html - title: 'GeoInfo' - path: /docs/reference/functions/providers_analytics_.geoinfo.html + path: /docs/reference/functions/v1_providers_analytics_.geoinfo.html - title: 'UserDimensions' - path: /docs/reference/functions/providers_analytics_.userdimensions.html + path: /docs/reference/functions/v1_providers_analytics_.userdimensions.html - title: 'UserPropertyValue' - path: /docs/reference/functions/providers_analytics_.userpropertyvalue.html + path: /docs/reference/functions/v1_providers_analytics_.userpropertyvalue.html - title: 'functions.auth' - path: /docs/reference/functions/providers_auth_.html + path: /docs/reference/functions/v1_providers_auth_.html section: - title: 'UserBuilder' - path: /docs/reference/functions/providers_auth_.userbuilder.html + path: /docs/reference/functions/v1_providers_auth_.userbuilder.html - title: 'UserInfo' - path: /docs/reference/functions/providers_auth_.html#userinfo + path: /docs/reference/functions/v1_providers_auth_.html#userinfo - title: 'UserRecordMetadata' - path: /docs/reference/functions/providers_auth_.userrecordmetadata.html + path: /docs/reference/functions/v1_providers_auth_.userrecordmetadata.html - title: 'UserRecord' - path: /docs/reference/functions/providers_auth_.html#userrecord + path: /docs/reference/functions/v1_providers_auth_.html#userrecord - title: 'functions.firestore' - path: /docs/reference/functions/providers_firestore_.html + path: /docs/reference/functions/v1_providers_firestore_.html section: - title: 'DocumentBuilder' - path: /docs/reference/functions/providers_firestore_.documentbuilder.html + path: /docs/reference/functions/v1_providers_firestore_.documentbuilder.html - title: 'DocumentSnapshot' - path: /docs/reference/functions/providers_firestore_.html#documentsnapshot + path: /docs/reference/functions/v1_providers_firestore_.html#documentsnapshot - title: 'functions.database' - path: /docs/reference/functions/providers_database_.html + path: /docs/reference/functions/v1_providers_database_.html section: - title: 'DataSnapshot' - path: /docs/reference/functions/providers_database_.datasnapshot.html + path: /docs/reference/functions/v1_providers_database_.datasnapshot.html - title: 'RefBuilder' - path: /docs/reference/functions/providers_database_.refbuilder.html + path: /docs/reference/functions/v1_providers_database_.refbuilder.html - title: 'InstanceBuilder' - path: /docs/reference/functions/providers_database_.instancebuilder.html + path: /docs/reference/functions/v1_providers_database_.instancebuilder.html - title: 'functions.https' - path: /docs/reference/functions/providers_https_.html + path: /docs/reference/functions/v1_providers_https_.html section: - title: 'HttpsError' - path: /docs/reference/functions/providers_https_.httpserror.html + path: /docs/reference/functions/v1_providers_https_.httpserror.html - title: 'CallableContext' - path: /docs/reference/functions/providers_https_.callablecontext.html + path: /docs/reference/functions/v1_providers_https_.callablecontext.html - title: 'functions.logger' - path: /docs/reference/functions/logger_.html + path: /docs/reference/functions/logger_index_.html section: - title: 'LogEntry' - path: /docs/reference/functions/logger_.logentry.html + path: /docs/reference/functions/logger_index_.logentry.html - title: 'functions.pubsub' - path: /docs/reference/functions/providers_pubsub_.html + path: /docs/reference/functions/v1_providers_pubsub_.html section: - title: 'Message' - path: /docs/reference/functions/providers_pubsub_.message.html + path: /docs/reference/functions/v1_providers_pubsub_.message.html - title: 'TopicBuilder' - path: /docs/reference/functions/providers_pubsub_.topicbuilder.html + path: /docs/reference/functions/v1_providers_pubsub_.topicbuilder.html - title: 'ScheduleBuilder' - path: /docs/reference/functions/providers_pubsub_.schedulebuilder.html + path: /docs/reference/functions/v1_providers_pubsub_.schedulebuilder.html - title: 'functions.remoteconfig' - path: /docs/reference/functions/providers_remoteconfig_.html + path: /docs/reference/functions/v1_providers_remoteconfig_.html section: - title: 'RemoteConfigUser' - path: /docs/reference/functions/providers_remoteconfig_.remoteconfiguser.html + path: /docs/reference/functions/v1_providers_remoteconfig_.remoteconfiguser.html - title: 'TemplateVersion' - path: /docs/reference/functions/providers_remoteconfig_.templateversion.html + path: /docs/reference/functions/v1_providers_remoteconfig_.templateversion.html - title: 'functions.storage' - path: /docs/reference/functions/providers_storage_.html + path: /docs/reference/functions/v1_providers_storage_.html section: - title: 'BucketBuilder' - path: /docs/reference/functions/providers_storage_.bucketbuilder.html + path: /docs/reference/functions/v1_providers_storage_.bucketbuilder.html - title: 'ObjectBuilder' - path: /docs/reference/functions/providers_storage_.objectbuilder.html + path: /docs/reference/functions/v1_providers_storage_.objectbuilder.html - title: 'ObjectMetadata' - path: /docs/reference/functions/providers_storage_.objectmetadata.html + path: /docs/reference/functions/v1_providers_storage_.objectmetadata.html - title: 'functions.testLab' - path: /docs/reference/functions/providers_testlab_.html + path: /docs/reference/functions/v1_providers_testlab_.html section: - title: 'testLab.clientInfo' - path: /docs/reference/functions/providers_testlab_.clientinfo.html + path: /docs/reference/functions/v1_providers_testlab_.clientinfo.html - title: 'testLab.resultStorage' - path: /docs/reference/functions/providers_testlab_.resultstorage.html + path: /docs/reference/functions/v1_providers_testlab_.resultstorage.html - title: 'testLab.testMatrix' - path: /docs/reference/functions/providers_testlab_.testmatrix.html + path: /docs/reference/functions/v1_providers_testlab_.testmatrix.html - title: 'testLab.testMatrixBuilder' - path: /docs/reference/functions/providers_testlab_.testmatrixbuilder.html + path: /docs/reference/functions/v1_providers_testlab_.testmatrixbuilder.html - title: 'functions.handler' - path: /docs/reference/functions/handler_builder_.html + path: /docs/reference/functions/v1_handler_builder_.html section: - title: 'HandlerBuilder' - path: /docs/reference/functions/handler_builder_.handlerbuilder.html + path: /docs/reference/functions/v1_handler_builder_.handlerbuilder.html diff --git a/docgen/generate-docs.js b/docgen/generate-docs.js index d36edb7e8..2f8b9abb0 100644 --- a/docgen/generate-docs.js +++ b/docgen/generate-docs.js @@ -26,9 +26,9 @@ const repoPath = path.resolve(`${__dirname}/..`); // Command-line options. const { source: sourceFile } = yargs .option('source', { - default: `${repoPath}/src`, + default: `${repoPath}/src/{v1,logger}`, describe: 'Typescript source file(s)', - type: 'string' + type: 'string', }) .version(false) .help().argv; @@ -38,7 +38,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 } = require('jsdom'); const typeMap = require('./type-aliases.json'); @@ -72,7 +72,7 @@ function runTypedoc() { * @param {string} subdir Subdir to move files out of. */ async function moveFilesToRoot(subdir) { - await exec(`mv ${docPath}/${subdir}/* ${docPath}`) + await exec(`mv ${docPath}/${subdir}/* ${docPath}`); await exec(`rmdir ${docPath}/${subdir}`); } @@ -86,9 +86,11 @@ async function renameFiles() { const files = await fs.readdir(docPath); const renames = []; for (const file of files) { - if (file.startsWith("_") && file.endsWith("html")) { + if (file.startsWith('_') && file.endsWith('html')) { let newFileName = file.substring(1); - renames.push(fs.rename(`${docPath}/${file}`, `${docPath}/${newFileName}`)); + renames.push( + fs.rename(`${docPath}/${file}`, `${docPath}/${newFileName}`) + ); } } await Promise.all(renames); @@ -125,11 +127,13 @@ function addTypeAliasLinks(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 fileTags = htmlDom.window.document.querySelectorAll( + '.tsd-signature-type' + ); + for (const tag of fileTags) { const mapping = typeMap[tag.textContent]; if (mapping) { - console.log('Adding link to '+tag.textContent+" documentation."); + console.log('Adding link to ' + tag.textContent + ' documentation.'); // Add the corresponding document link to this type const linkChild = htmlDom.window.document.createElement('a'); @@ -138,7 +142,7 @@ function addTypeAliasLinks(data) { tag.textContent = null; tag.appendChild(linkChild); } - }); + } return htmlDom.serialize(); } @@ -152,13 +156,13 @@ function addTypeAliasLinks(data) { function generateTempHomeMdFile(tocRaw, homeRaw) { const { toc } = yaml.safeLoad(tocRaw); let tocPageLines = [homeRaw, '# API Reference']; - toc.forEach(group => { + for (const group of toc) { tocPageLines.push(`\n## [${group.title}](${stripPath(group.path)})`); const section = group.section || []; - section.forEach(item => { + for (const item of section) { tocPageLines.push(`- [${item.title}](${stripPath(item.path)})`); - }); - }); + } + } return fs.writeFile(tempHomePath, tocPageLines.join('\n')); } @@ -176,10 +180,10 @@ async function checkForMissingFilesAndFixFilenameCase(tocText) { // Get filenames from toc.yaml. const filenames = tocText .split('\n') - .filter(line => line.includes('path:')) - .map(line => line.split(devsitePath)[1]); + .filter((line) => line.includes('path:')) + .map((line) => line.split(devsitePath)[1].replace(/#.*$/, '')); // Logs warning to console if a file from TOC is not found. - const fileCheckPromises = filenames.map(async filename => { + const fileCheckPromises = filenames.map(async (filename) => { // Warns if file does not exist, fixes filename case if it does. // Preferred filename for devsite should be capitalized and taken from // toc.yaml. @@ -211,29 +215,28 @@ async function checkForMissingFilesAndFixFilenameCase(tocText) { */ async function checkForUnlistedFiles(filenamesFromToc, shouldRemove) { const files = await fs.readdir(docPath); - const htmlFiles = files - .filter(filename => filename.slice(-4) === 'html'); + const htmlFiles = files.filter((filename) => filename.slice(-4) === 'html'); const removePromises = []; const filesToRemove = htmlFiles - .filter(filename => !filenamesFromToc.includes(filename)) - .filter(filename => filename !== 'index' && filename != 'globals'); + .filter((filename) => !filenamesFromToc.includes(filename)) + .filter((filename) => filename !== 'index' && filename != 'globals'); if (filesToRemove.length && !shouldRemove) { // This is just a warning, it doesn't need to finish before // the process continues. console.warn( - `Unlisted files: ${filesToRemove.join(", ")} generated ` + + `Unlisted files: ${filesToRemove.join(', ')} generated ` + `but not listed in toc.yaml.` ); return htmlFiles; } - await Promise.all(filesToRemove.map(filename => { - console.log( - `REMOVING ${docPath}/${filename} - not listed in toc.yaml.` - ); - return fs.unlink(`${docPath}/${filename})`); - })); - return htmlFiles.filter(filename => filenamesFromToc.includes(filename)) + await Promise.all( + filesToRemove.map((filename) => { + console.log(`REMOVING ${docPath}/${filename} - not listed in toc.yaml.`); + return fs.unlink(`${docPath}/${filename})`); + }) + ); + return htmlFiles.filter((filename) => filenamesFromToc.includes(filename)); } /** @@ -243,10 +246,10 @@ async function checkForUnlistedFiles(filenamesFromToc, shouldRemove) { * @param {Array} htmlFiles List of html files found in generated dir. */ async function writeGeneratedFileList(htmlFiles) { - const fileList = htmlFiles.map(filename => { + const fileList = htmlFiles.map((filename) => { return { title: filename, - path: `${devsitePath}${filename}` + path: `${devsitePath}${filename}`, }; }); const generatedTocYAML = yaml.safeDump({ toc: fileList }); @@ -262,10 +265,10 @@ async function writeGeneratedFileList(htmlFiles) { */ function fixAllLinks(htmlFiles) { const writePromises = []; - htmlFiles.forEach(file => { + for (const file of htmlFiles) { // Update links in each html file to match flattened file structure. writePromises.push(fixLinks(`${docPath}/${file}`)); - }); + } return Promise.all(writePromises); } @@ -281,12 +284,12 @@ function fixAllLinks(htmlFiles) { * links as needed. * 5) Check for mismatches between TOC list and generated file list. */ -(async function() { +(async function () { try { const [tocRaw, homeRaw] = await Promise.all([ fs.readFile(`${contentPath}/toc.yaml`, 'utf8'), - fs.readFile(`${contentPath}/HOME.md`, 'utf8') - ]) + fs.readFile(`${contentPath}/HOME.md`, 'utf8'), + ]); // Run main Typedoc process (uses index.d.ts and generated temp file above). await generateTempHomeMdFile(tocRaw, homeRaw); @@ -324,7 +327,9 @@ function fixAllLinks(htmlFiles) { // Check for files listed in TOC that are missing and warn if so. // Not blocking. - const filenamesFromToc = await checkForMissingFilesAndFixFilenameCase(tocRaw); + const filenamesFromToc = await checkForMissingFilesAndFixFilenameCase( + tocRaw + ); // Check for files that exist but aren't listed in the TOC and warn. // (If API is node, actually remove the file.) @@ -340,13 +345,15 @@ function fixAllLinks(htmlFiles) { const data = await fs.readFile(`${docPath}/index.html`, 'utf8'); // String to include devsite local variables. const localVariablesIncludeString = `{% include "docs/web/_local_variables.html" %}\n`; - await fs.writeFile(`${docPath}/index.html`, localVariablesIncludeString + data); + await fs.writeFile( + `${docPath}/index.html`, + localVariablesIncludeString + data + ); } catch (err) { - if (err.stdout) { - console.error(err.stdout); - } else { - console.error(err); + if (err.stdout) { + console.error(err.stdout); + } else { + console.error(err); + } } -} })(); - diff --git a/docgen/theme/helpers/cleanBreadcrumb.js b/docgen/theme/helpers/cleanBreadcrumb.js new file mode 100644 index 000000000..ad52e64a7 --- /dev/null +++ b/docgen/theme/helpers/cleanBreadcrumb.js @@ -0,0 +1,4 @@ +exports.cleanBreadcrumb = function (value) { + const parts = value.replace(/"/g, '').split('/'); + return parts[parts.length - 1]; +}; diff --git a/docgen/theme/partials/breadcrumb.hbs b/docgen/theme/partials/breadcrumb.hbs index db115163f..6a2147724 100644 --- a/docgen/theme/partials/breadcrumb.hbs +++ b/docgen/theme/partials/breadcrumb.hbs @@ -3,7 +3,7 @@ {{#with parent}}{{> breadcrumb}}{{/with}}
  • {{#if url}} - {{name}}. + {{cleanBreadcrumb name}}. {{else}} {{name}} {{/if}} diff --git a/docgen/theme/partials/header.hbs b/docgen/theme/partials/header.hbs index 4aee65a6b..edb115a07 100644 --- a/docgen/theme/partials/header.hbs +++ b/docgen/theme/partials/header.hbs @@ -6,7 +6,7 @@ {{else}}