Update api-documenter for devsite changes.

Author: hsubox76

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,15 @@ 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',
+      parameterShortName: '-p',
+      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 +116,7 @@ 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,18 @@ 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,14 @@ 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`
+      `# ${headingNode.title}\n`
     );
-    stringBuilder.append('{% block body %}\n');
 
     this._markdownEmitter.emit(stringBuilder, output, {
       contextApiItem: apiItem,
@@ -179,8 +184,6 @@ export class MarkdownDocumenter {
       }
     });
 
-    stringBuilder.append('{% endblock body %}\n');
-
     let pageContent: string = stringBuilder.toString();
 
     if (this._pluginLoader.markdownDocumenterFeature) {
@@ -253,9 +256,8 @@ export class MarkdownDocumenter {
         output.push(
           new DocHeading({
             configuration,
-            title: `${packageName}${
-              apiItem.displayName && '/' + apiItem.displayName
-            }`
+            title: `${packageName}${apiItem.displayName && '/' + apiItem.displayName
+              }`
           })
         );
         break;