Add MarkdownDocumenterFeature.onFinished() and MarkdownDocumenterFeatureContext members

Author: octogonz

apps/api-documenter/src/cli/GenerateAction.ts

@@ -7,12 +7,10 @@ import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
 import { BaseAction } from './BaseAction';
 import { DocumenterConfig } from '../documenters/DocumenterConfig';
 import { ExperimentalYamlDocumenter } from '../documenters/ExperimentalYamlDocumenter';
-import { IConfigFile } from '../documenters/IConfigFile';
 
 import { ApiModel } from '@microsoft/api-extractor-model';
 import { FileSystem } from '@microsoft/node-core-library';
 import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
-import { PluginLoader } from '../plugin/PluginLoader';
 
 export class GenerateAction extends BaseAction {
   constructor(parser: ApiDocumenterCommandLine) {
@@ -38,18 +36,15 @@ export class GenerateAction extends BaseAction {
       }
     }
 
-    const configFile: IConfigFile = DocumenterConfig.loadFile(configFilePath);
-
-    const pluginLoader: PluginLoader = new PluginLoader();
-    pluginLoader.load(configFile.plugins || [], configFilePath);
+    const documenterConfig: DocumenterConfig = DocumenterConfig.loadFile(configFilePath);
 
     const apiModel: ApiModel = this.buildApiModel();
 
-    if (configFile.outputTarget === 'markdown') {
-      const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, pluginLoader);
+    if (documenterConfig.configFile.outputTarget === 'markdown') {
+      const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, documenterConfig);
       markdownDocumenter.generateFiles(this.outputFolder);
     } else {
-      const yamlDocumenter: ExperimentalYamlDocumenter = new ExperimentalYamlDocumenter(apiModel, configFile);
+      const yamlDocumenter: ExperimentalYamlDocumenter = new ExperimentalYamlDocumenter(apiModel, documenterConfig);
       yamlDocumenter.generateFiles(this.outputFolder);
     }
 

apps/api-documenter/src/cli/MarkdownAction.ts

@@ -5,7 +5,6 @@ import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
 import { BaseAction } from './BaseAction';
 import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
 import { ApiModel } from '@microsoft/api-extractor-model';
-import { PluginLoader } from '../plugin/PluginLoader';
 
 export class MarkdownAction extends BaseAction {
   constructor(parser: ApiDocumenterCommandLine) {
@@ -20,8 +19,7 @@ export class MarkdownAction extends BaseAction {
   protected onExecute(): Promise<void> { // override
     const apiModel: ApiModel = this.buildApiModel();
 
-    const pluginLoader: PluginLoader = new PluginLoader();
-    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, pluginLoader);
+    const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter(apiModel, undefined);
     markdownDocumenter.generateFiles(this.outputFolder);
     return Promise.resolve();
   }

apps/api-documenter/src/documenters/DocumenterConfig.ts

@@ -11,6 +11,9 @@ import { IConfigFile } from './IConfigFile';
  * represents the raw JSON file structure.
  */
 export class DocumenterConfig {
+  public readonly configFilePath: string;
+  public readonly configFile: IConfigFile;
+
   /**
    * The JSON Schema for API Extractor config file (api-extractor.schema.json).
    */
@@ -25,9 +28,14 @@ export class DocumenterConfig {
   /**
    * Load and validate an api-documenter.json file.
    */
-  public static loadFile(configFilePath: string): IConfigFile {
+  public static loadFile(configFilePath: string): DocumenterConfig {
     const configFile: IConfigFile = JsonFile.loadAndValidate(configFilePath, DocumenterConfig.jsonSchema);
 
-    return configFile;
+    return new DocumenterConfig(path.resolve(configFilePath), configFile);
+  }
+
+  private constructor(filePath: string, configFile: IConfigFile) {
+    this.configFilePath = filePath;
+    this.configFile = configFile;
   }
 }

apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts

@@ -5,9 +5,10 @@ import { PackageName } from '@microsoft/node-core-library';
 import { DocComment, DocInlineTag } from '@microsoft/tsdoc';
 import { ApiModel, ApiItem, ApiItemKind, ApiDocumentedItem } from '@microsoft/api-extractor-model';
 
-import { IConfigFile, IConfigTableOfContents } from './IConfigFile';
+import { IConfigTableOfContents } from './IConfigFile';
 import { IYamlTocItem, IYamlTocFile } from '../yaml/IYamlTocFile';
 import { YamlDocumenter } from './YamlDocumenter';
+import { DocumenterConfig } from './DocumenterConfig';
 
 /**
  * EXPERIMENTAL - This documenter is a prototype of a new config file driven mode of operation for
@@ -18,9 +19,9 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
   private _tocPointerMap: { [key: string]: IYamlTocItem };
   private _catchAllPointer: IYamlTocItem;
 
-  public constructor(apiModel: ApiModel, configFile: IConfigFile) {
+  public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {
     super(apiModel);
-    this._config = configFile.tableOfContents!;
+    this._config = documenterConfig.configFile.tableOfContents!;
 
     this._tocPointerMap = {};
 

apps/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -52,36 +52,62 @@ import { DocNoteBox } from '../nodes/DocNoteBox';
 import { Utilities } from '../utils/Utilities';
 import { CustomMarkdownEmitter } from '../markdown/CustomMarkdownEmitter';
 import { PluginLoader } from '../plugin/PluginLoader';
-import { IMarkdownDocumenterFeatureOnBeforeWritePageArgs } from '../plugin/MarkdownDocumenterFeature';
+import {
+  IMarkdownDocumenterFeatureOnBeforeWritePageArgs,
+  MarkdownDocumenterFeatureContext
+} from '../plugin/MarkdownDocumenterFeature';
+import { DocumenterConfig } from './DocumenterConfig';
+import { MarkdownDocumenterAccessor } from '../plugin/MarkdownDocumenterAccessor';
 
 /**
  * Renders API documentation in the Markdown file format.
  * For more info:  https://en.wikipedia.org/wiki/Markdown
  */
 export class MarkdownDocumenter {
   private readonly _apiModel: ApiModel;
-  private readonly _pluginLoader: PluginLoader;
+  private readonly _documenterConfig: DocumenterConfig | undefined;
   private readonly _tsdocConfiguration: TSDocConfiguration;
   private readonly _markdownEmitter: CustomMarkdownEmitter;
   private _outputFolder: string;
+  private readonly _pluginLoader: PluginLoader;
 
-  public constructor(apiModel: ApiModel, pluginLoader: PluginLoader) {
+  public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig | undefined) {
     this._apiModel = apiModel;
-    this._pluginLoader = pluginLoader;
+    this._documenterConfig = documenterConfig;
     this._tsdocConfiguration = CustomDocNodes.configuration;
     this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
+
+    this._pluginLoader = new PluginLoader();
   }
 
   public generateFiles(outputFolder: string): void {
     this._outputFolder = outputFolder;
 
+    if (this._documenterConfig) {
+      this._pluginLoader.load(this._documenterConfig, () => {
+        return new MarkdownDocumenterFeatureContext({
+          apiModel: this._apiModel,
+          outputFolder: outputFolder,
+          documenter: new MarkdownDocumenterAccessor({
+            getLinkForApiItem: (apiItem: ApiItem) => {
+              return this._getLinkFilenameForApiItem(apiItem);
+            }
+          })
+        });
+      });
+    }
+
     console.log();
     this._deleteOldOutputFiles();
 
     for (const apiPackage of this._apiModel.packages) {
       console.log(`Writing ${apiPackage.name} package`);
       this._writeApiItemPage(apiPackage);
     }
+
+    if (this._pluginLoader.markdownDocumenterFeature) {
+      this._pluginLoader.markdownDocumenterFeature.onFinished({ });
+    }
   }
 
   private _writeApiItemPage(apiItem: ApiItem): void {

apps/api-documenter/src/index.ts

@@ -5,9 +5,11 @@ export {
   IFeatureDefinition,
   IApiDocumenterPluginManifest
 } from './plugin/IApiDocumenterPluginManifest';
+export { MarkdownDocumenterAccessor } from './plugin/MarkdownDocumenterAccessor';
 export {
   MarkdownDocumenterFeatureContext,
   IMarkdownDocumenterFeatureOnBeforeWritePageArgs,
+  IMarkdownDocumenterFeatureOnFinishedArgs,
   MarkdownDocumenterFeature
 } from './plugin/MarkdownDocumenterFeature';
 export {

apps/api-documenter/src/plugin/MarkdownDocumenterAccessor.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { ApiItem } from '@microsoft/api-extractor-model';
+
+/** @internal */
+export interface IMarkdownDocumenterAccessorImplementation {
+  getLinkForApiItem(apiItem: ApiItem): string | undefined;
+}
+
+/**
+ * Provides access to the documenter that is generating the output.
+ *
+ * @privateRemarks
+ * This class is wrapper that provides access to the underlying MarkdownDocumenter, while hiding the implementation
+ * details to ensure that the plugin API contract is stable.
+ *
+ * @public
+ */
+export class MarkdownDocumenterAccessor {
+  private _implementation: IMarkdownDocumenterAccessorImplementation;
+
+  /** @internal */
+  constructor (implementation: IMarkdownDocumenterAccessorImplementation) {
+    this._implementation = implementation;
+  }
+
+  /**
+   * For a given `ApiItem`, return its markdown hyperlink.
+   *
+   * @returns The hyperlink, or `undefined` if the `ApiItem` object does not have a hyperlink.
+   */
+  public getLinkForApiItem(apiItem: ApiItem): string | undefined {
+    return this._implementation.getLinkForApiItem(apiItem);
+  }
+}

apps/api-documenter/src/plugin/MarkdownDocumenterFeature.ts

@@ -2,15 +2,36 @@
 // See LICENSE in the project root for license information.
 
 import { PluginFeature } from './PluginFeature';
-import { ApiItem } from '@microsoft/api-extractor-model';
+import { ApiItem, ApiModel } from '@microsoft/api-extractor-model';
+import { MarkdownDocumenterAccessor } from './MarkdownDocumenterAccessor';
 
 /**
  * Context object for {@link MarkdownDocumenterFeature}.
  *
  * @public
  */
 export class MarkdownDocumenterFeatureContext {
+  /** @internal */
+  public constructor(options: MarkdownDocumenterFeatureContext) {
+    this.apiModel = options.apiModel;
+    this.outputFolder = options.outputFolder;
+    this.documenter = options.documenter;
+  }
+
+  /**
+   * Provides access to the `ApiModel` for the documentation being generated.
+   */
+  public readonly apiModel: ApiModel;
+
+  /**
+   * The full path to the output folder.
+   */
+  public readonly outputFolder: string;
 
+  /**
+   * Exposes functionality of the documenter.
+   */
+  public readonly documenter: MarkdownDocumenterAccessor;
 }
 
 /**
@@ -34,6 +55,13 @@ export interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
   readonly outputFilename: string;
 }
 
+/**
+ * Event arguments for MarkdownDocumenterFeature.onFinished()
+ * @public
+ */
+export interface IMarkdownDocumenterFeatureOnFinishedArgs {
+}
+
 /**
  * Inherit from this base class to implement an API Documenter plugin feature that customizes
  * the generation of markdown output.
@@ -44,10 +72,19 @@ export class MarkdownDocumenterFeature extends PluginFeature {
   public context: MarkdownDocumenterFeatureContext;
 
   /**
-   * This event function is called before writing a page.
+   * This event occurs before each markdown file is written.  It provides an opportunity to customize the
+   * content of the file.
    * @virtual
    */
   public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
     // (implemented by child class)
   }
+
+  /**
+   * This event occurs after all output files have been written.
+   * @virtual
+   */
+  public onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void {
+    // (implemented by child class)
+  }
 }

apps/api-documenter/src/plugin/PluginLoader.ts

@@ -4,10 +4,10 @@
 import * as path from 'path';
 import * as resolve from 'resolve';
 
-import { IConfigPlugin } from '../documenters/IConfigFile';
 import { IApiDocumenterPluginManifest, IFeatureDefinition } from './IApiDocumenterPluginManifest';
 import { MarkdownDocumenterFeature, MarkdownDocumenterFeatureContext } from './MarkdownDocumenterFeature';
 import { PluginFeatureInitialization } from './PluginFeature';
+import { DocumenterConfig } from '../documenters/DocumenterConfig';
 
 interface ILoadedPlugin {
   packageName: string;
@@ -17,9 +17,9 @@ interface ILoadedPlugin {
 export class PluginLoader {
   public markdownDocumenterFeature: MarkdownDocumenterFeature | undefined;
 
-  public load(configPlugins: IConfigPlugin[], configFilePath: string): void {
-    const configFileFolder: string = path.dirname(configFilePath);
-    for (const configPlugin of configPlugins) {
+  public load(documenterConfig: DocumenterConfig, createContext: () => MarkdownDocumenterFeatureContext): void {
+    const configFileFolder: string = path.dirname(documenterConfig.configFilePath);
+    for (const configPlugin of (documenterConfig.configFile.plugins || [])) {
       try {
         // Look for the package name in the same place as the config file
         const resolvedEntryPointPath: string = resolve.sync(configPlugin.packageName, {
@@ -69,10 +69,8 @@ export class PluginLoader {
               throw new Error('A MarkdownDocumenterFeature is already loaded');
             }
 
-            const context: MarkdownDocumenterFeatureContext = new MarkdownDocumenterFeatureContext();
-
             const initialization: PluginFeatureInitialization  = new PluginFeatureInitialization();
-            initialization._context = context;
+            initialization._context = createContext();
 
             let markdownDocumenterFeature: MarkdownDocumenterFeature | undefined = undefined;
             try {

common/reviews/api/api-documenter.api.md

@@ -5,6 +5,7 @@
 ```ts
 
 import { ApiItem } from '@microsoft/api-extractor-model';
+import { ApiModel } from '@microsoft/api-extractor-model';
 
 // @public
 export interface IApiDocumenterPluginManifest {
@@ -28,16 +29,36 @@ export interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
     pageContent: string;
 }
 
+// @public
+export interface IMarkdownDocumenterFeatureOnFinishedArgs {
+}
+
+// @public
+export class MarkdownDocumenterAccessor {
+    // Warning: (ae-forgotten-export) The symbol "IMarkdownDocumenterAccessorImplementation" needs to be exported by the entry point index.d.ts
+    // 
+    // @internal
+    constructor(implementation: IMarkdownDocumenterAccessorImplementation);
+    getLinkForApiItem(apiItem: ApiItem): string | undefined;
+    }
+
 // @public
 export class MarkdownDocumenterFeature extends PluginFeature {
     // (undocumented)
     context: MarkdownDocumenterFeatureContext;
     // @virtual
     onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void;
+    // @virtual
+    onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void;
 }
 
 // @public
 export class MarkdownDocumenterFeatureContext {
+    // @internal
+    constructor(options: MarkdownDocumenterFeatureContext);
+    readonly apiModel: ApiModel;
+    readonly documenter: MarkdownDocumenterAccessor;
+    readonly outputFolder: string;
 }
 
 // @public