Update api-documenter to work with new devsite changes (#6449)

Author: hsubox76

repo-scripts/api-documenter/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @firebase/api-documenter
 
+## 0.2.0
+### Minor Changes
+
+- [#6449](https://github.com/firebase/firebase-js-sdk/pull/6449) Updates to work with devsite changes. Added a required `--project` flag for generating markdown docs.
 ## 0.1.2
 ### Patch Changes
 

repo-scripts/api-documenter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firebase/api-documenter",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Read JSON files from api-extractor, generate documentation pages",
   "repository": {
     "directory": "repo-scripts/documenter",

repo-scripts/api-documenter/src/cli/BaseAction.ts

@@ -41,12 +41,14 @@ export interface IBuildApiModelResult {
   inputFolder: string;
   outputFolder: string;
   addFileNameSuffix: boolean;
+  projectName?: string;
 }
 
 export abstract class BaseAction extends CommandLineAction {
   private _inputFolderParameter!: CommandLineStringParameter;
   private _outputFolderParameter!: CommandLineStringParameter;
   private _fileNameSuffixParameter!: CommandLineFlagParameter;
+  private _projectNameParameter!: CommandLineStringParameter;
 
   protected onDefineParameters(): void {
     // override
@@ -79,6 +81,14 @@ export abstract class BaseAction extends CommandLineAction {
         `This is to avoid name conflict in case packageA also has, for example, an entry point with the same name in lowercase.` +
         `This option is specifically designed for the Admin SDK where such case occurs.`
     });
+
+    this._projectNameParameter = this.defineStringParameter({
+      parameterLongName: '--project',
+      argumentName: 'PROJECT',
+      description:
+        `Name of the project (js, admin, functions, etc.). This will be ` +
+        `used in the devsite header path to the _project.yaml file.`
+    });
   }
 
   protected buildApiModel(): IBuildApiModelResult {
@@ -105,7 +115,13 @@ export abstract class BaseAction extends CommandLineAction {
 
     this._applyInheritDoc(apiModel, apiModel);
 
-    return { apiModel, inputFolder, outputFolder, addFileNameSuffix };
+    return {
+      apiModel,
+      inputFolder,
+      outputFolder,
+      addFileNameSuffix,
+      projectName: this._projectNameParameter.value
+    };
   }
 
   // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer

repo-scripts/api-documenter/src/cli/MarkdownAction.ts

@@ -35,13 +35,19 @@ export class MarkdownAction extends BaseAction {
 
   protected async onExecute(): Promise<void> {
     // override
-    const { apiModel, outputFolder, addFileNameSuffix } = this.buildApiModel();
+    const { apiModel, outputFolder, addFileNameSuffix, projectName } =
+      this.buildApiModel();
+
+    if (!projectName) {
+      throw new Error('No project name provided. Use --project.');
+    }
 
     const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({
       apiModel,
       documenterConfig: undefined,
       outputFolder,
-      addFileNameSuffix
+      addFileNameSuffix,
+      projectName
     });
     markdownDocumenter.generateFiles();
   }

repo-scripts/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -92,6 +92,7 @@ export interface IMarkdownDocumenterOptions {
   documenterConfig: DocumenterConfig | undefined;
   outputFolder: string;
   addFileNameSuffix: boolean;
+  projectName: string;
 }
 
 /**
@@ -106,12 +107,14 @@ export class MarkdownDocumenter {
   private readonly _outputFolder: string;
   private readonly _pluginLoader: PluginLoader;
   private readonly _addFileNameSuffix: boolean;
+  private readonly _projectName: string;
 
   public constructor(options: IMarkdownDocumenterOptions) {
     this._apiModel = options.apiModel;
     this._documenterConfig = options.documenterConfig;
     this._outputFolder = options.outputFolder;
     this._addFileNameSuffix = options.addFileNameSuffix;
+    this._projectName = options.projectName;
     this._tsdocConfiguration = CustomDocNodes.configuration;
     this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
 
@@ -165,12 +168,13 @@ export class MarkdownDocumenter {
 
     // devsite headers
     stringBuilder.append(
-      '{% extends "_internal/templates/reference.html" %}\n'
+      `Project: /docs/reference/${this._projectName}/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+`
     );
-    stringBuilder.append(
-      `{% block title %}${headingNode.title}{% endblock title %}\n`
-    );
-    stringBuilder.append('{% block body %}\n');
+
+    stringBuilder.append(`# ${headingNode.title}\n`);
 
     this._markdownEmitter.emit(stringBuilder, output, {
       contextApiItem: apiItem,
@@ -179,8 +183,6 @@ export class MarkdownDocumenter {
       }
     });
 
-    stringBuilder.append('{% endblock body %}\n');
-
     let pageContent: string = stringBuilder.toString();
 
     if (this._pluginLoader.markdownDocumenterFeature) {

scripts/docgen/docgen.ts

@@ -27,7 +27,8 @@ import * as yargs from 'yargs';
  * Add to devsite files to alert anyone trying to make a documentation fix
  * to the generated files.
  */
-const GOOGLE3_HEADER = `{% comment %}
+const GOOGLE3_HEADER = `
+{% comment %}
 DO NOT EDIT THIS FILE!
 This is generated by the JS SDK team, and any local changes will be
 overwritten. Changes should be made in the source code at
@@ -110,7 +111,16 @@ async function generateDocs(forDevsite: boolean = false) {
 
   await spawn(
     'yarn',
-    [command, 'markdown', '--input', 'temp', '--output', outputFolder],
+    [
+      command,
+      'markdown',
+      '--input',
+      'temp',
+      '--output',
+      outputFolder,
+      '--project',
+      'js'
+    ],
     { stdio: 'inherit' }
   );
 
@@ -119,7 +129,10 @@ async function generateDocs(forDevsite: boolean = false) {
     for (const mdFile of mdFiles) {
       const fullPath = join(projectRoot, outputFolder, mdFile);
       const content = fs.readFileSync(fullPath, 'utf-8');
-      fs.writeFileSync(fullPath, GOOGLE3_HEADER + content);
+      fs.writeFileSync(
+        fullPath,
+        content.replace('\n# ', `\n${GOOGLE3_HEADER}\n# `)
+      );
     }
   }