Merge cbf1beb into 1703bb3

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,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,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;

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,7 @@ 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 +120,7 @@ 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# `));
     }
   }