Merge pull request #399 from Microsoft/pgonzal/ad-command-line

pgonzal · web-flow · commit a6af4411f214 · 2017-10-19T18:12:39.000-07:00
Add a command line for api-documenter
diff --git a/libraries/api-documenter/ad.cmd b/libraries/api-documenter/ad.cmd
@@ -0,0 +1,3 @@
+@ECHO OFF
+@SETLOCAL
+node "%~dp0\lib\start" %*
diff --git a/libraries/api-documenter/bin/api-documenter b/libraries/api-documenter/bin/api-documenter
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../lib/start.js')
diff --git a/libraries/api-documenter/src/cli/ApiDocumenterCommandLine.ts b/libraries/api-documenter/src/cli/ApiDocumenterCommandLine.ts
@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { CommandLineParser } from '@microsoft/ts-command-line';
+import { MarkdownAction } from './MarkdownAction';
+import { YamlAction } from './YamlAction';
+
+export class ApiDocumenterCommandLine extends CommandLineParser {
+  constructor() {
+    super({
+      toolFilename: 'api-documenter',
+      toolDescription: 'Reads *.api.json files produced by api-extractor, '
+        + ' and generates API documentation in various output formats'
+    });
+    this._populateActions();
+  }
+
+  protected onDefineParameters(): void { // override
+    // No parameters
+  }
+
+  private _populateActions(): void {
+    this.addAction(new MarkdownAction(this));
+    this.addAction(new YamlAction(this));
+  }
+}
diff --git a/libraries/api-documenter/src/cli/BaseAction.ts b/libraries/api-documenter/src/cli/BaseAction.ts
@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as fsx from 'fs-extra';
+import * as path from 'path';
+
+import {
+  CommandLineAction,
+  CommandLineStringParameter
+} from '@microsoft/ts-command-line';
+
+import { DocItemSet } from '../utils/DocItemSet';
+
+export abstract class BaseAction extends CommandLineAction {
+  protected inputFolder: string;
+  protected outputFolder: string;
+
+  private _inputFolderParameter: CommandLineStringParameter;
+  private _outputFolderParameter: CommandLineStringParameter;
+
+  protected onDefineParameters(): void { // override
+    this._inputFolderParameter = this.defineStringParameter({
+      parameterLongName: '--input-folder',
+      parameterShortName: '-i',
+      key: 'FOLDER1',
+      description: `Specifies the input folder containing the *.api.json files to be processed.`
+        + ` If omitted, the default is "./input"`
+    });
+
+    this._outputFolderParameter = this.defineStringParameter({
+      parameterLongName: '--output-folder',
+      parameterShortName: '-o',
+      key: 'FOLDER2',
+      description: `Specifies the output folder where the documentation will be written.`
+        + ` ANY EXISTING CONTENTS WILL BE DELETED!`
+        + ` If omitted, the default is "./${this.options.actionVerb}"`
+    });
+  }
+
+  protected buildDocItemSet(): DocItemSet {
+    const docItemSet: DocItemSet = new DocItemSet();
+
+    this.inputFolder = this._inputFolderParameter.value || './input';
+    if (!fsx.existsSync(this.inputFolder)) {
+      throw new Error('The input folder does not exist: ' + this.inputFolder);
+    }
+
+    this.outputFolder = this._outputFolderParameter.value || `./${this.options.actionVerb}`;
+    if (!fsx.existsSync(this.outputFolder)) {
+      throw new Error('The output folder does not exist: ' + this.outputFolder);
+    }
+
+    for (const filename of fsx.readdirSync(this.inputFolder)) {
+      if (filename.match(/\.api\.json$/i)) {
+        console.log(`Reading ${filename}`);
+        const filenamePath: string = path.join(this.inputFolder, filename);
+        docItemSet.loadApiJsonFile(filenamePath);
+      }
+    }
+
+    docItemSet.calculateReferences();
+
+    return docItemSet;
+  }
+}
diff --git a/libraries/api-documenter/src/cli/MarkdownAction.ts b/libraries/api-documenter/src/cli/MarkdownAction.ts
@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
+import { BaseAction } from './BaseAction';
+import { DocItemSet } from '../utils/DocItemSet';
+import { MarkdownDocumenter } from '../markdown/MarkdownDocumenter';
+
+export class MarkdownAction extends BaseAction {
+  constructor(parser: ApiDocumenterCommandLine) {
+    super({
+      actionVerb: 'markdown',
+      summary: 'Generate documentation as Markdown files (*.md)',
+      documentation: 'Generate documentation as Markdown files (*.md)'
+    });
+  }
+
+  protected onExecute(): void { // override
+    const docItemSet: DocItemSet = this.buildDocItemSet();
+    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(docItemSet);
+    markdownDocumenter.generateFiles(this.outputFolder);
+  }
+}
diff --git a/libraries/api-documenter/src/cli/YamlAction.ts b/libraries/api-documenter/src/cli/YamlAction.ts
@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
+import { BaseAction } from './BaseAction';
+import { DocItemSet } from '../utils/DocItemSet';
+import { YamlDocumenter } from '../yaml/YamlDocumenter';
+
+export class YamlAction extends BaseAction {
+  constructor(parser: ApiDocumenterCommandLine) {
+    super({
+      actionVerb: 'yaml',
+      summary: 'Generate documentation as universal reference YAML files (*.yml)',
+      documentation: 'Generate documentation as YAML files (*.yml)'
+    });
+  }
+
+  protected onExecute(): void { // override
+    const docItemSet: DocItemSet = this.buildDocItemSet();
+    const yamlDocumenter: YamlDocumenter = new YamlDocumenter(docItemSet);
+    yamlDocumenter.generateFiles(this.outputFolder);
+  }
+}
diff --git a/libraries/api-documenter/src/index.ts b/libraries/api-documenter/src/index.ts
diff --git a/libraries/api-documenter/src/markdown/MarkdownDocumenter.ts b/libraries/api-documenter/src/markdown/MarkdownDocumenter.ts
@@ -22,16 +22,21 @@ import {
   MarkupStructuredElement
 } from '@microsoft/api-extractor';
 
-import { DocItemSet, DocItem, DocItemKind, IDocItemSetResolveResult } from '../DocItemSet';
-import { RenderingHelpers } from '../RenderingHelpers';
-import { MarkupBuilder } from '../MarkupBuilder';
-import { MarkdownRenderer, IMarkdownRenderApiLinkArgs } from '../MarkdownRenderer';
+import {
+  DocItemSet,
+  DocItem,
+  DocItemKind,
+  IDocItemSetResolveResult
+} from '../utils/DocItemSet';
+import { Utilities } from '../utils/Utilities';
+import { MarkupBuilder } from '../utils/MarkupBuilder';
+import { MarkdownRenderer, IMarkdownRenderApiLinkArgs } from '../utils/MarkdownRenderer';
 
 /**
  * Renders API documentation in the Markdown file format.
  * For more info:  https://en.wikipedia.org/wiki/Markdown
  */
-export class MarkdownGenerator {
+export class MarkdownDocumenter {
   private _docItemSet: DocItemSet;
   private _outputFolder: string;
 
@@ -57,7 +62,7 @@ export class MarkdownGenerator {
   private _writePackagePage(docPackage: DocItem): void {
     console.log(`Writing ${docPackage.name} package`);
 
-    const unscopedPackageName: string = RenderingHelpers.getUnscopedPackageName(docPackage.name);
+    const unscopedPackageName: string = Utilities.getUnscopedPackageName(docPackage.name);
 
     const markupPage: IMarkupPage = MarkupBuilder.createPage(`${unscopedPackageName} package`);
     this._writeBreadcrumb(markupPage, docPackage);
@@ -229,7 +234,7 @@ export class MarkdownGenerator {
           // TODO: Extract constructor into its own section
           const constructorTitle: MarkupBasicElement[] = [
             MarkupBuilder.createApiLink(
-              [MarkupBuilder.createCode(RenderingHelpers.getConciseSignature(docMember.name, apiMember), 'javascript')],
+              [MarkupBuilder.createCode(Utilities.getConciseSignature(docMember.name, apiMember), 'javascript')],
               docMember.getApiReference())
           ];
 
@@ -247,7 +252,7 @@ export class MarkdownGenerator {
         case 'method':
           const methodTitle: MarkupBasicElement[] = [
             MarkupBuilder.createApiLink(
-              [MarkupBuilder.createCode(RenderingHelpers.getConciseSignature(docMember.name, apiMember), 'javascript')],
+              [MarkupBuilder.createCode(Utilities.getConciseSignature(docMember.name, apiMember), 'javascript')],
               docMember.getApiReference())
           ];
 
@@ -334,7 +339,7 @@ export class MarkdownGenerator {
         case 'method':
           const methodTitle: MarkupBasicElement[] = [
             MarkupBuilder.createApiLink(
-              [MarkupBuilder.createCode(RenderingHelpers.getConciseSignature(docMember.name, apiMember), 'javascript')],
+              [MarkupBuilder.createCode(Utilities.getConciseSignature(docMember.name, apiMember), 'javascript')],
               docMember.getApiReference())
           ];
 
@@ -596,7 +601,7 @@ export class MarkdownGenerator {
     let baseName: string = '';
     for (const part of docItem.getHierarchy()) {
       if (part.kind === DocItemKind.Package) {
-        baseName = RenderingHelpers.getUnscopedPackageName(part.name);
+        baseName = Utilities.getUnscopedPackageName(part.name);
       } else {
         baseName += '.' + part.name;
       }
diff --git a/libraries/api-documenter/src/start.ts b/libraries/api-documenter/src/start.ts
@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import * as os from 'os';
+import * as colors from 'colors';
+import * as path from 'path';
+
+import { ApiDocumenterCommandLine } from './cli/ApiDocumenterCommandLine';
+
+const myPackageJsonFilename: string = path.resolve(path.join(
+  __dirname, '..', 'package.json')
+);
+const myPackageJson: { version: string } = require(myPackageJsonFilename);
+
+console.log(os.EOL + colors.bold(`api-documenter ${myPackageJson.version} `
+  + colors.cyan(' - http://aka.ms/extractor') + os.EOL));
+
+const parser: ApiDocumenterCommandLine = new ApiDocumenterCommandLine();
+
+parser.execute();
diff --git a/libraries/api-documenter/src/utils/DocItemSet.ts b/libraries/api-documenter/src/utils/DocItemSet.ts
@@ -8,7 +8,7 @@ import {
   IApiItemReference
 } from '@microsoft/api-extractor';
 
-import { RenderingHelpers } from './RenderingHelpers';
+import { Utilities } from './Utilities';
 
 export enum DocItemKind {
   Package,
@@ -227,7 +227,7 @@ export class DocItemSet {
       closestMatch: undefined
     };
 
-    const packageName: string = RenderingHelpers.getScopedPackageName(reference.scopeName, reference.packageName);
+    const packageName: string = Utilities.getScopedPackageName(reference.scopeName, reference.packageName);
     if (!packageName) {
       // This would indicate an invalid data file, since API Extractor is supposed to normalize this
       throw new Error('resolveApiItemReference() failed because the packageName should not be empty');
diff --git a/libraries/api-documenter/src/utils/MarkdownRenderer.ts b/libraries/api-documenter/src/utils/MarkdownRenderer.ts
diff --git a/libraries/api-documenter/src/utils/MarkupBuilder.ts b/libraries/api-documenter/src/utils/MarkupBuilder.ts
diff --git a/libraries/api-documenter/src/utils/Utilities.ts b/libraries/api-documenter/src/utils/Utilities.ts
@@ -7,7 +7,7 @@ import {
   IApiConstructor
 } from '@microsoft/api-extractor';
 
-export class RenderingHelpers {
+export class Utilities {
 
   /**
    * Used to validate a data structure before converting to JSON or YAML format.  Reports
@@ -26,7 +26,7 @@ export class RenderingHelpers {
         if (value === undefined) {
           throw new Error(`The key "${keyWithPath}" is undefined`);
         }
-        RenderingHelpers.validateNoUndefinedMembers(value, keyWithPath);
+        Utilities.validateNoUndefinedMembers(value, keyWithPath);
       }
     }
 
diff --git a/libraries/api-documenter/src/utils/test/ExpectedOutput.md b/libraries/api-documenter/src/utils/test/ExpectedOutput.md
diff --git a/libraries/api-documenter/src/utils/test/MarkdownRenderer.test.ts b/libraries/api-documenter/src/utils/test/MarkdownRenderer.test.ts
@@ -12,7 +12,7 @@ import { IMarkupPage } from '@microsoft/api-extractor';
 import { MarkupBuilder } from '../MarkupBuilder';
 import { MarkdownRenderer } from '../MarkdownRenderer';
 
-describe('MarkdownPageRenderer', () => {
+describe('MarkdownRenderer', () => {
   it('renders markdown', (done: MochaDone) => {
 
     const outputFolder: string = FileDiffTest.prepareFolder(__dirname, 'MarkdownPageRenderer');
diff --git a/libraries/api-documenter/src/yaml/YamlDocumenter.ts b/libraries/api-documenter/src/yaml/YamlDocumenter.ts
@@ -17,7 +17,7 @@ import {
   IApiInterface
 } from '@microsoft/api-extractor';
 
-import { DocItemSet, DocItem, DocItemKind, IDocItemSetResolveResult } from '../DocItemSet';
+import { DocItemSet, DocItem, DocItemKind, IDocItemSetResolveResult } from '../utils/DocItemSet';
 import {
   IYamlApiFile,
   IYamlItem,
@@ -28,16 +28,16 @@ import {
   IYamlTocFile,
   IYamlTocItem
 } from './IYamlTocFile';
-import { RenderingHelpers } from '../RenderingHelpers';
-import { MarkupBuilder } from '../MarkupBuilder';
-import { MarkdownRenderer, IMarkdownRenderApiLinkArgs } from '../MarkdownRenderer';
+import { Utilities } from '../utils/Utilities';
+import { MarkupBuilder } from '../utils/MarkupBuilder';
+import { MarkdownRenderer, IMarkdownRenderApiLinkArgs } from '../utils/MarkdownRenderer';
 
 const yamlApiSchema: JsonSchema = JsonSchema.fromFile(path.join(__dirname, 'typescript.schema.json'));
 
 /**
  * Writes documentation in the Universal Reference YAML file format, as defined by typescript.schema.json.
  */
-export class YamlGenerator {
+export class YamlDocumenter {
   private _docItemSet: DocItemSet;
   private _outputFolder: string;
 
@@ -152,7 +152,7 @@ export class YamlGenerator {
       }
 
       const tocItem: IYamlTocItem = {
-        name: RenderingHelpers.getUnscopedPackageName(docItem.name),
+        name: Utilities.getUnscopedPackageName(docItem.name),
         uid: this._getUid(docItem)
       };
 
@@ -271,7 +271,7 @@ export class YamlGenerator {
 
   private _populateYamlMethod(yamlItem: Partial<IYamlItem>, docItem: DocItem): void {
     const apiMethod: IApiMethod | IApiConstructor = docItem.apiItem as IApiMethod;
-    yamlItem.name = RenderingHelpers.getConciseSignature(docItem.name, apiMethod);
+    yamlItem.name = Utilities.getConciseSignature(docItem.name, apiMethod);
 
     const syntax: IYamlSyntax = {
       content: apiMethod.signature
@@ -376,7 +376,7 @@ export class YamlGenerator {
     for (const current of docItem.getHierarchy()) {
       switch (current.kind) {
         case DocItemKind.Package:
-          result += RenderingHelpers.getUnscopedPackageName(current.name);
+          result += Utilities.getUnscopedPackageName(current.name);
           break;
         default:
           result += '.';
@@ -393,7 +393,7 @@ export class YamlGenerator {
     for (const current of docItem.getHierarchy()) {
       switch (current.kind) {
         case DocItemKind.Package:
-          result += RenderingHelpers.getUnscopedPackageName(current.name);
+          result += Utilities.getUnscopedPackageName(current.name);
           break;
         default:
           if (current.parent && current.parent.kind === DocItemKind.Package) {

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+@ECHO OFF`
	`2`	`+@SETLOCAL`
	`3`	`+node "%~dp0\lib\start" %*`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+#!/usr/bin/env node`
	`2`	`+require('../lib/start.js')`