diff --git a/docgen/toc.ts b/docgen/toc.ts new file mode 100644 index 000000000..d552a9cba --- /dev/null +++ b/docgen/toc.ts @@ -0,0 +1,124 @@ +/** + * @license + * Copyright 2022 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * Forked of https://github.com/firebase/firebase-js-sdk/blob/5ce06766303b92fea969c58172a7c1ab8695e21e/repo-scripts/api-documenter/src/toc.ts. + */ +import { writeFileSync } from 'fs'; +import { resolve } from 'path'; + +import yargs from 'yargs'; +import * as yaml from 'js-yaml'; +import { FileSystem } from '@rushstack/node-core-library'; + +export interface TocGenerationOptions { + inputFolder: string; + outputFolder: string; + g3Path: string; +} + +interface TocItem { + title: string; + path: string; + section?: TocItem[]; + status?: 'experimental'; +} + +function fileExt(f: string) { + const parts = f.split('.'); + if (parts.length < 2) { + return ''; + } + return parts.pop(); +} + +export function generateToc({ + inputFolder, + g3Path, + outputFolder, +}: TocGenerationOptions) { + const asObj = FileSystem.readFolder(inputFolder) + .filter((f) => fileExt(f) === 'md') + .reduce((acc, f) => { + const parts = f.split('.'); + parts.pop(); // Get rid of file extenion (.md) + + let cursor = acc; + for (const p of parts) { + cursor[p] = cursor[p] || {}; + cursor = cursor[p]; + } + return acc; + }, {} as any); + + function toToc(obj, prefix = ''): TocItem[] { + const toc: TocItem[] = []; + for (const key of Object.keys(obj)) { + const path = prefix?.length ? `${prefix}.${key}` : key; + const section = toToc(obj[key], path); + const tic: TocItem = { + title: key, + path: `${g3Path}/${path}.md`, + }; + if (section.length > 0) { + tic.section = section; + } + toc.push(tic); + } + return toc; + } + + const toc: TocItem[] = [ + { + title: 'firebase-functions', + status: 'experimental', + path: `${g3Path}/firebase-functions.md`, + }, + ...toToc(asObj['firebase-functions'], 'firebase-functions'), + ]; + + writeFileSync( + resolve(outputFolder, 'toc.yaml'), + yaml.dump( + { toc }, + { + quotingType: '"', + } + ) + ); +} + +const { input, output, path } = yargs(process.argv.slice(2)) + .option('input', { + alias: 'i', + describe: 'input folder containing the *.api.json files to be processed.', + default: './input', + }) + .option('output', { + alias: 'o', + describe: 'destination for the generated toc content.', + default: './toc', + }) + .option('path', { + alias: 'p', + describe: 'specifies the path where the reference docs resides (e.g. g3)', + default: '/', + }) + .help().argv; + +FileSystem.ensureFolder(output); +generateToc({ inputFolder: input, g3Path: path, outputFolder: output }); diff --git a/package.json b/package.json index 0b2911c92..aca2baeba 100644 --- a/package.json +++ b/package.json @@ -161,7 +161,8 @@ "docgen:v1:gen": "api-documenter-fire markdown -i docgen/v1 -o docgen/v1/markdown && api-documenter-fire toc -i docgen/v1 -o docgen/v1/markdown/toc -p /docs/reference/functions", "docgen:v1": "npm run build && npm run docgen:v1:extract && npm run docgen:v1:gen", "docgen:v2:extract": "api-extractor run -c docgen/api-extractor.v2.json --local", - "docgen:v2:gen": "api-documenter-fire markdown -i docgen/v2 -o docgen/v2/markdown && api-documenter-fire toc -i docgen/v2 -o docgen/v2/markdown/toc -p /docs/reference/functions/v2", + "docgen:v2:toc": "ts-node docgen/toc.ts --input docgen/v2/markdown --output docgen/v2/markdown/toc --path /docs/functions/beta/reference", + "docgen:v2:gen": "api-documenter-fire markdown -i docgen/v2 -o docgen/v2/markdown && npm run docgen:v2:toc", "docgen:v2": "npm run build && npm run docgen:v2:extract && npm run docgen:v2:gen", "build:pack": "rm -rf lib && npm install && tsc -p tsconfig.release.json && npm pack", "build:release": "npm ci --production && npm install --no-save typescript firebase-admin && tsc -p tsconfig.release.json", @@ -196,6 +197,7 @@ "@types/node": "^8.10.50", "@types/node-fetch": "^3.0.3", "@types/sinon": "^7.0.13", + "api-extractor-model-me": "^0.1.1", "chai": "^4.2.0", "chai-as-promised": "^7.1.1", "child-process-promise": "^2.2.1",