UNPKG

7.1 kBTypeScriptView Raw
1/**
2 * API Documenter generates an API reference website from the .api.json files created by API Extractor.
3 * The `@microsoft/api-documenter` package provides the command-line tool. It also exposes a developer API that you
4 * can use to create plugins that customize how API Documenter generates documentation.
5 *
6 * @packageDocumentation
7 */
8
9import type { ApiItem } from '@microsoft/api-extractor-model';
10import type { ApiModel } from '@microsoft/api-extractor-model';
11
12/**
13 * The manifest for an API Documenter plugin.
14 *
15 * @remarks
16 * An API documenter plugin is an NPM package. By convention, the NPM package name should have the prefix
17 * `doc-plugin-`. Its main entry point should export an object named `apiDocumenterPluginManifest` which implements
18 * the `IApiDocumenterPluginManifest` interface.
19 *
20 * For example:
21 * ```ts
22 * class MyMarkdownDocumenter extends MarkdownDocumenterFeature {
23 * public onInitialized(): void {
24 * console.log('MyMarkdownDocumenter: onInitialized()');
25 * }
26 * }
27 *
28 * export const apiDocumenterPluginManifest: IApiDocumenterPluginManifest = {
29 * manifestVersion: 1000,
30 * features: [
31 * {
32 * featureName: 'my-markdown-documenter',
33 * kind: 'MarkdownDocumenterFeature',
34 * subclass: MyMarkdownDocumenter
35 * }
36 * ]
37 * };
38 * ```
39 * @public
40 */
41export declare interface IApiDocumenterPluginManifest {
42 /**
43 * The manifest version number. For now, this must always be `1000`.
44 */
45 manifestVersion: 1000;
46 /**
47 * The list of features provided by this plugin.
48 */
49 features: IFeatureDefinition[];
50}
51
52/**
53 * Defines a "feature" that is provided by an API Documenter plugin. A feature is a user-defined module
54 * that customizes the behavior of API Documenter.
55 *
56 * @public
57 */
58export declare interface IFeatureDefinition {
59 /**
60 * The name of this feature, as it will appear in the config file.
61 *
62 * The name should consist of one or more words separated by hyphens. Each word should consist of lower case
63 * letters and numbers. Example: `my-feature`
64 */
65 featureName: string;
66 /**
67 * Determines the kind of feature. The specified value is the name of the base class that `subclass` inherits from.
68 *
69 * @remarks
70 * For now, `MarkdownDocumenterFeature` is the only supported value.
71 */
72 kind: 'MarkdownDocumenterFeature';
73 /**
74 * Your subclass that extends from the base class.
75 */
76 subclass: {
77 new (initialization: PluginFeatureInitialization): MarkdownDocumenterFeature;
78 };
79}
80
81/** @internal */
82declare interface IMarkdownDocumenterAccessorImplementation {
83 getLinkForApiItem(apiItem: ApiItem): string | undefined;
84}
85
86/**
87 * Event arguments for MarkdownDocumenterFeature.onBeforeWritePage()
88 * @public
89 */
90export declare interface IMarkdownDocumenterFeatureOnBeforeWritePageArgs {
91 /**
92 * The API item corresponding to this page.
93 */
94 readonly apiItem: ApiItem;
95 /**
96 * The page content. The {@link MarkdownDocumenterFeature.onBeforeWritePage} handler can reassign this
97 * string to customize the page appearance.
98 */
99 pageContent: string;
100 /**
101 * The filename where the output will be written.
102 */
103 readonly outputFilename: string;
104}
105
106/**
107 * Event arguments for MarkdownDocumenterFeature.onFinished()
108 * @public
109 */
110export declare interface IMarkdownDocumenterFeatureOnFinishedArgs {
111}
112
113/**
114 * Provides access to the documenter that is generating the output.
115 *
116 * @privateRemarks
117 * This class is wrapper that provides access to the underlying MarkdownDocumenter, while hiding the implementation
118 * details to ensure that the plugin API contract is stable.
119 *
120 * @public
121 */
122export declare class MarkdownDocumenterAccessor {
123 private _implementation;
124 /** @internal */
125 constructor(implementation: IMarkdownDocumenterAccessorImplementation);
126 /**
127 * For a given `ApiItem`, return its markdown hyperlink.
128 *
129 * @returns The hyperlink, or `undefined` if the `ApiItem` object does not have a hyperlink.
130 */
131 getLinkForApiItem(apiItem: ApiItem): string | undefined;
132}
133
134/**
135 * Inherit from this base class to implement an API Documenter plugin feature that customizes
136 * the generation of markdown output.
137 *
138 * @public
139 */
140export declare class MarkdownDocumenterFeature extends PluginFeature {
141 /** {@inheritdoc PluginFeature.context} */
142 context: MarkdownDocumenterFeatureContext;
143 /**
144 * This event occurs before each markdown file is written. It provides an opportunity to customize the
145 * content of the file.
146 * @virtual
147 */
148 onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void;
149 /**
150 * This event occurs after all output files have been written.
151 * @virtual
152 */
153 onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void;
154 static [Symbol.hasInstance](instance: object): boolean;
155}
156
157/**
158 * Context object for {@link MarkdownDocumenterFeature}.
159 * Exposes various services that can be used by a plugin.
160 *
161 * @public
162 */
163export declare class MarkdownDocumenterFeatureContext {
164 /**
165 * Provides access to the `ApiModel` for the documentation being generated.
166 */
167 readonly apiModel: ApiModel;
168 /**
169 * The full path to the output folder.
170 */
171 readonly outputFolder: string;
172 /**
173 * Exposes functionality of the documenter.
174 */
175 readonly documenter: MarkdownDocumenterAccessor;
176 /** @internal */
177 constructor(options: MarkdownDocumenterFeatureContext);
178}
179
180/**
181 * The abstract base class for all API Documenter plugin features.
182 * @public
183 */
184export declare abstract class PluginFeature {
185 /**
186 * Exposes various services that can be used by a plugin.
187 */
188 context: PluginFeatureContext;
189 /**
190 * The subclass should pass the `initialization` through to the base class.
191 * Do not put custom initialization code in the constructor. Instead perform your initialization in the
192 * `onInitialized()` event function.
193 * @internal
194 */
195 constructor(initialization: PluginFeatureInitialization);
196 /**
197 * This event function is called after the feature is initialized, but before any processing occurs.
198 * @virtual
199 */
200 onInitialized(): void;
201 static [Symbol.hasInstance](instance: object): boolean;
202}
203
204/**
205 * Context object for {@link PluginFeature}.
206 * Exposes various services that can be used by a plugin.
207 *
208 * @public
209 */
210export declare class PluginFeatureContext {
211}
212
213/**
214 * This is an internal part of the plugin infrastructure.
215 *
216 * @remarks
217 * This object is the constructor parameter for API Documenter plugin features.
218 *
219 * @public
220 */
221export declare class PluginFeatureInitialization {
222 /** @internal */
223 _context: PluginFeatureContext;
224 /** @internal */
225 constructor();
226}
227
228export { }