@firebase/api-documenter 0.1.2-canary.233e117f0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @firebase/api-documenter
+
+## 0.1.2
+### Patch Changes
+
+- [#4931](https://github.com/firebase/firebase-js-sdk/pull/4931) Support toc generation for Firebase devsite.
+## 0.1.1
+### Patch Changes
+
+- [#4869](https://github.com/firebase/firebase-js-sdk/pull/4869) Generate API docs for namespace members

package/README.md

@@ -0,0 +1,16 @@
+# @firebase/api-documenter
+
+It is a fork of [API Documenter](https://github.com/microsoft/rushstack/tree/master/apps/api-documenter)
+It reads the *.api.json data files produced by [API Extractor](https://api-extractor.com/),
+and then generates files in [Markdown](https://en.wikipedia.org/wiki/Markdown) format suitable for displaying in Firebase Devsite.
+
+## Generate toc for Firebase devsite
+`api-documenter-fire toc -i temp -p "/docs/reference/js/v9"`
+
+`-i` and `-p` (`--host-path`) are required parameters.
+Use `-i` to specify the folder that contains api.json files.
+Use `-p` to specify the g3 path that contains the reference docs.
+
+By default, the command will create `toc.yaml` in folder `/toc`. To change the output folder, use the flag `-o`.
+
+To generate toc for the Firebase JS SDK, also set the flag `-j` to create the top level `firebase` toc item.

package/dist/cli/ApiDocumenterCommandLine.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CommandLineParser } from '@rushstack/ts-command-line';
+export declare class ApiDocumenterCommandLine extends CommandLineParser {
+    constructor();
+    protected onDefineParameters(): void;
+    private _populateActions;
+}

package/dist/cli/ApiDocumenterCommandLine.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiDocumenterCommandLine = void 0;
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+const ts_command_line_1 = require("@rushstack/ts-command-line");
+const MarkdownAction_1 = require("./MarkdownAction");
+const TocAction_1 = require("./TocAction");
+class ApiDocumenterCommandLine extends ts_command_line_1.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();
+    }
+    onDefineParameters() {
+        // override
+        // No parameters
+    }
+    _populateActions() {
+        this.addAction(new MarkdownAction_1.MarkdownAction(this));
+        this.addAction(new TocAction_1.TocAction(this));
+    }
+}
+exports.ApiDocumenterCommandLine = ApiDocumenterCommandLine;
+//# sourceMappingURL=ApiDocumenterCommandLine.js.map

package/dist/cli/ApiDocumenterCommandLine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiDocumenterCommandLine.js","sourceRoot":"","sources":["../../src/cli/ApiDocumenterCommandLine.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,4FAA4F;AAC5F,2DAA2D;AAE3D,gEAA+D;AAC/D,qDAAkD;AAClD,2CAAwC;AAExC,MAAa,wBAAyB,SAAQ,mCAAiB;IAC7D;QACE,KAAK,CAAC;YACJ,YAAY,EAAE,gBAAgB;YAC9B,eAAe,EACb,oDAAoD;gBACpD,6DAA6D;SAChE,CAAC,CAAC;QACH,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAES,kBAAkB;QAC1B,WAAW;QACX,gBAAgB;IAClB,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,SAAS,CAAC,IAAI,+BAAc,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,SAAS,CAAC,IAAI,qBAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC;CACF;AApBD,4DAoBC"}

package/dist/cli/BaseAction.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CommandLineAction } from '@rushstack/ts-command-line';
+import { ApiModel } from 'api-extractor-model-me';
+export interface IBuildApiModelResult {
+    apiModel: ApiModel;
+    inputFolder: string;
+    outputFolder: string;
+    addFileNameSuffix: boolean;
+}
+export declare abstract class BaseAction extends CommandLineAction {
+    private _inputFolderParameter;
+    private _outputFolderParameter;
+    private _fileNameSuffixParameter;
+    protected onDefineParameters(): void;
+    protected buildApiModel(): IBuildApiModelResult;
+    private _applyInheritDoc;
+    /**
+     * Copy the content from `sourceDocComment` to `targetDocComment`.
+     * This code is borrowed from DocCommentEnhancer as a temporary workaround.
+     */
+    private _copyInheritedDocs;
+}

package/dist/cli/BaseAction.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAction = void 0;
+const tslib_1 = require("tslib");
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+const path = tslib_1.__importStar(require("path"));
+const colors_1 = tslib_1.__importDefault(require("colors"));
+const ts_command_line_1 = require("@rushstack/ts-command-line");
+const node_core_library_1 = require("@rushstack/node-core-library");
+const api_extractor_model_me_1 = require("api-extractor-model-me");
+class BaseAction extends ts_command_line_1.CommandLineAction {
+    onDefineParameters() {
+        // override
+        this._inputFolderParameter = this.defineStringParameter({
+            parameterLongName: '--input-folder',
+            parameterShortName: '-i',
+            argumentName: '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',
+            argumentName: 'FOLDER2',
+            description: `Specifies the output folder where the documentation will be written.` +
+                ` ANY EXISTING CONTENTS WILL BE DELETED!` +
+                ` If omitted, the default is "./${this.actionName}"`
+        });
+        this._fileNameSuffixParameter = this.defineFlagParameter({
+            parameterLongName: '--name-suffix',
+            parameterShortName: '-s',
+            description: `Add suffix to interface and class names in the file path.` +
+                `For example, packageA.myinterface_i.md for MyInterface interface, ` +
+                `Add packageA.myclass_c.md for MyClass class.` +
+                `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.`
+        });
+    }
+    buildApiModel() {
+        const apiModel = new api_extractor_model_me_1.ApiModel();
+        const inputFolder = this._inputFolderParameter.value || './input';
+        if (!node_core_library_1.FileSystem.exists(inputFolder)) {
+            throw new Error('The input folder does not exist: ' + inputFolder);
+        }
+        const outputFolder = this._outputFolderParameter.value || `./${this.actionName}`;
+        node_core_library_1.FileSystem.ensureFolder(outputFolder);
+        const addFileNameSuffix = this._fileNameSuffixParameter.value;
+        for (const filename of node_core_library_1.FileSystem.readFolder(inputFolder)) {
+            if (filename.match(/\.api\.json$/i)) {
+                console.log(`Reading ${filename}`);
+                const filenamePath = path.join(inputFolder, filename);
+                apiModel.loadPackage(filenamePath);
+            }
+        }
+        this._applyInheritDoc(apiModel, apiModel);
+        return { apiModel, inputFolder, outputFolder, addFileNameSuffix };
+    }
+    // TODO: This is a temporary workaround.  The long term plan is for API Extractor's DocCommentEnhancer
+    // to apply all @inheritDoc tags before the .api.json file is written.
+    // See DocCommentEnhancer._applyInheritDoc() for more info.
+    _applyInheritDoc(apiItem, apiModel) {
+        if (apiItem instanceof api_extractor_model_me_1.ApiDocumentedItem) {
+            if (apiItem.tsdocComment) {
+                const inheritDocTag = apiItem.tsdocComment.inheritDocTag;
+                if (inheritDocTag && inheritDocTag.declarationReference) {
+                    // Attempt to resolve the declaration reference
+                    const result = apiModel.resolveDeclarationReference(inheritDocTag.declarationReference, apiItem);
+                    if (result.errorMessage) {
+                        console.log(colors_1.default.yellow(`Warning: Unresolved @inheritDoc tag for ${apiItem.displayName}: ` +
+                            result.errorMessage));
+                    }
+                    else {
+                        if (result.resolvedApiItem instanceof api_extractor_model_me_1.ApiDocumentedItem &&
+                            result.resolvedApiItem.tsdocComment &&
+                            result.resolvedApiItem !== apiItem) {
+                            this._copyInheritedDocs(apiItem.tsdocComment, result.resolvedApiItem.tsdocComment);
+                        }
+                    }
+                }
+            }
+        }
+        // Recurse members
+        if (api_extractor_model_me_1.ApiItemContainerMixin.isBaseClassOf(apiItem)) {
+            for (const member of apiItem.members) {
+                this._applyInheritDoc(member, apiModel);
+            }
+        }
+    }
+    /**
+     * Copy the content from `sourceDocComment` to `targetDocComment`.
+     * This code is borrowed from DocCommentEnhancer as a temporary workaround.
+     */
+    _copyInheritedDocs(targetDocComment, sourceDocComment) {
+        targetDocComment.summarySection = sourceDocComment.summarySection;
+        targetDocComment.remarksBlock = sourceDocComment.remarksBlock;
+        targetDocComment.params.clear();
+        for (const param of sourceDocComment.params) {
+            targetDocComment.params.add(param);
+        }
+        for (const typeParam of sourceDocComment.typeParams) {
+            targetDocComment.typeParams.add(typeParam);
+        }
+        targetDocComment.returnsBlock = sourceDocComment.returnsBlock;
+        targetDocComment.inheritDocTag = undefined;
+    }
+}
+exports.BaseAction = BaseAction;
+//# sourceMappingURL=BaseAction.js.map

package/dist/cli/BaseAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseAction.js","sourceRoot":"","sources":["../../src/cli/BaseAction.ts"],"names":[],"mappings":"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"}

package/dist/cli/MarkdownAction.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
+import { BaseAction } from './BaseAction';
+export declare class MarkdownAction extends BaseAction {
+    constructor(parser: ApiDocumenterCommandLine);
+    protected onExecute(): Promise<void>;
+}

package/dist/cli/MarkdownAction.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkdownAction = void 0;
+const tslib_1 = require("tslib");
+const BaseAction_1 = require("./BaseAction");
+const MarkdownDocumenter_1 = require("../documenters/MarkdownDocumenter");
+class MarkdownAction extends BaseAction_1.BaseAction {
+    constructor(parser) {
+        super({
+            actionName: 'markdown',
+            summary: 'Generate documentation as Markdown files (*.md)',
+            documentation: 'Generates API documentation as a collection of files in' +
+                ' Markdown format, suitable for example for publishing on a GitHub site.'
+        });
+    }
+    onExecute() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // override
+            const { apiModel, outputFolder, addFileNameSuffix } = this.buildApiModel();
+            const markdownDocumenter = new MarkdownDocumenter_1.MarkdownDocumenter({
+                apiModel,
+                documenterConfig: undefined,
+                outputFolder,
+                addFileNameSuffix
+            });
+            markdownDocumenter.generateFiles();
+        });
+    }
+}
+exports.MarkdownAction = MarkdownAction;
+//# sourceMappingURL=MarkdownAction.js.map

package/dist/cli/MarkdownAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownAction.js","sourceRoot":"","sources":["../../src/cli/MarkdownAction.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;;AAMH,6CAA0C;AAC1C,0EAAuE;AAEvE,MAAa,cAAe,SAAQ,uBAAU;IAC5C,YAAmB,MAAgC;QACjD,KAAK,CAAC;YACJ,UAAU,EAAE,UAAU;YACtB,OAAO,EAAE,iDAAiD;YAC1D,aAAa,EACX,yDAAyD;gBACzD,yEAAyE;SAC5E,CAAC,CAAC;IACL,CAAC;IAEe,SAAS;;YACvB,WAAW;YACX,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAE3E,MAAM,kBAAkB,GAAuB,IAAI,uCAAkB,CAAC;gBACpE,QAAQ;gBACR,gBAAgB,EAAE,SAAS;gBAC3B,YAAY;gBACZ,iBAAiB;aAClB,CAAC,CAAC;YACH,kBAAkB,CAAC,aAAa,EAAE,CAAC;QACrC,CAAC;KAAA;CACF;AAvBD,wCAuBC"}

package/dist/cli/TocAction.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
+import { BaseAction } from './BaseAction';
+export declare class TocAction extends BaseAction {
+    private _g3PathParameter;
+    private _jsSDKParameter;
+    constructor(parser: ApiDocumenterCommandLine);
+    protected onDefineParameters(): void;
+    protected onExecute(): Promise<void>;
+}

package/dist/cli/TocAction.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TocAction = void 0;
+const tslib_1 = require("tslib");
+const BaseAction_1 = require("./BaseAction");
+const toc_1 = require("../toc");
+class TocAction extends BaseAction_1.BaseAction {
+    constructor(parser) {
+        super({
+            actionName: 'toc',
+            summary: 'Generate TOC(table of content) for Firebase devsite.',
+            documentation: 'Generate TOC(table of content) for Firebase devsite.'
+        });
+    }
+    onDefineParameters() {
+        super.onDefineParameters();
+        this._g3PathParameter = this.defineStringParameter({
+            parameterLongName: '--host-path',
+            parameterShortName: '-p',
+            argumentName: 'HOSTPATH',
+            description: `Specifies the path where the reference docs resides (e.g. g3).
+                Used to generate paths in the toc`
+        });
+        this._jsSDKParameter = this.defineFlagParameter({
+            parameterLongName: '--js-sdk',
+            parameterShortName: '-j',
+            description: `Generating toc for the Firebase JS SDK.` +
+                `It will create an artificial top level toc item "firebase".`
+        });
+    }
+    onExecute() {
+        return tslib_1.__awaiter(this, void 0, void 0, function* () {
+            // override
+            const { apiModel, outputFolder, addFileNameSuffix } = this.buildApiModel();
+            const g3Path = this._g3PathParameter.value;
+            const jsSdk = this._jsSDKParameter.value;
+            if (!g3Path) {
+                throw new Error('--g3-path is a required to generate toc, but it is not provided');
+            }
+            toc_1.generateToc({
+                apiModel,
+                outputFolder,
+                addFileNameSuffix,
+                g3Path,
+                jsSdk
+            });
+        });
+    }
+}
+exports.TocAction = TocAction;
+//# sourceMappingURL=TocAction.js.map

package/dist/cli/TocAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TocAction.js","sourceRoot":"","sources":["../../src/cli/TocAction.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;;AAOH,6CAA0C;AAC1C,gCAAqC;AAErC,MAAa,SAAU,SAAQ,uBAAU;IAGvC,YAAmB,MAAgC;QACjD,KAAK,CAAC;YACJ,UAAU,EAAE,KAAK;YACjB,OAAO,EAAE,sDAAsD;YAC/D,aAAa,EAAE,sDAAsD;SACtE,CAAC,CAAC;IACL,CAAC;IAES,kBAAkB;QAC1B,KAAK,CAAC,kBAAkB,EAAE,CAAC;QAE3B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,qBAAqB,CAAC;YACjD,iBAAiB,EAAE,aAAa;YAChC,kBAAkB,EAAE,IAAI;YACxB,YAAY,EAAE,UAAU;YACxB,WAAW,EAAE;kDAC+B;SAC7C,CAAC,CAAC;QAEH,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,mBAAmB,CAAC;YAC9C,iBAAiB,EAAE,UAAU;YAC7B,kBAAkB,EAAE,IAAI;YACxB,WAAW,EACT,yCAAyC;gBACzC,6DAA6D;SAChE,CAAC,CAAC;IACL,CAAC;IAEe,SAAS;;YACvB,WAAW;YACX,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;YAC3E,MAAM,MAAM,GAAuB,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC;YAC/D,MAAM,KAAK,GAAY,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;YAElD,IAAI,CAAC,MAAM,EAAE;gBACX,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;aACH;YAED,iBAAW,CAAC;gBACV,QAAQ;gBACR,YAAY;gBACZ,iBAAiB;gBACjB,MAAM;gBACN,KAAK;aACN,CAAC,CAAC;QACL,CAAC;KAAA;CACF;AAnDD,8BAmDC"}

package/dist/documenters/DocumenterConfig.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { JsonSchema, NewlineKind } from '@rushstack/node-core-library';
+import { IConfigFile } from './IConfigFile';
+/**
+ * Helper for loading the api-documenter.json file format.  Later when the schema is more mature,
+ * this class will be used to represent the validated and normalized configuration, whereas `IConfigFile`
+ * represents the raw JSON file structure.
+ */
+export declare class DocumenterConfig {
+    readonly configFilePath: string;
+    readonly configFile: IConfigFile;
+    /**
+     * Specifies what type of newlines API Documenter should use when writing output files.  By default, the output files
+     * will be written with Windows-style newlines.
+     */
+    readonly newlineKind: NewlineKind;
+    /**
+     * The JSON Schema for API Extractor config file (api-extractor.schema.json).
+     */
+    static readonly jsonSchema: JsonSchema;
+    /**
+     * The config file name "api-extractor.json".
+     */
+    static readonly FILENAME: string;
+    private constructor();
+    /**
+     * Load and validate an api-documenter.json file.
+     */
+    static loadFile(configFilePath: string): DocumenterConfig;
+}

package/dist/documenters/DocumenterConfig.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumenterConfig = void 0;
+const tslib_1 = require("tslib");
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+const path = tslib_1.__importStar(require("path"));
+const node_core_library_1 = require("@rushstack/node-core-library");
+/**
+ * Helper for loading the api-documenter.json file format.  Later when the schema is more mature,
+ * this class will be used to represent the validated and normalized configuration, whereas `IConfigFile`
+ * represents the raw JSON file structure.
+ */
+class DocumenterConfig {
+    constructor(filePath, configFile) {
+        this.configFilePath = filePath;
+        this.configFile = configFile;
+        switch (configFile.newlineKind) {
+            case 'lf':
+                this.newlineKind = "\n" /* Lf */;
+                break;
+            case 'os':
+                this.newlineKind = "os" /* OsDefault */;
+                break;
+            default:
+                this.newlineKind = "\r\n" /* CrLf */;
+                break;
+        }
+    }
+    /**
+     * Load and validate an api-documenter.json file.
+     */
+    static loadFile(configFilePath) {
+        const configFile = node_core_library_1.JsonFile.loadAndValidate(configFilePath, DocumenterConfig.jsonSchema);
+        return new DocumenterConfig(path.resolve(configFilePath), configFile);
+    }
+}
+exports.DocumenterConfig = DocumenterConfig;
+/**
+ * The JSON Schema for API Extractor config file (api-extractor.schema.json).
+ */
+DocumenterConfig.jsonSchema = node_core_library_1.JsonSchema.fromFile(path.join(__dirname, '..', 'schemas', 'api-documenter.schema.json'));
+/**
+ * The config file name "api-extractor.json".
+ */
+DocumenterConfig.FILENAME = 'api-documenter.json';
+//# sourceMappingURL=DocumenterConfig.js.map

package/dist/documenters/DocumenterConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumenterConfig.js","sourceRoot":"","sources":["../../src/documenters/DocumenterConfig.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;;AAEH,4FAA4F;AAC5F,2DAA2D;AAE3D,mDAA6B;AAC7B,oEAIsC;AAGtC;;;;GAIG;AACH,MAAa,gBAAgB;IAsB3B,YAAoB,QAAgB,EAAE,UAAuB;QAC3D,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,QAAQ,UAAU,CAAC,WAAW,EAAE;YAC9B,KAAK,IAAI;gBACP,IAAI,CAAC,WAAW,gBAAiB,CAAC;gBAClC,MAAM;YACR,KAAK,IAAI;gBACP,IAAI,CAAC,WAAW,uBAAwB,CAAC;gBACzC,MAAM;YACR;gBACE,IAAI,CAAC,WAAW,oBAAmB,CAAC;gBACpC,MAAM;SACT;IACH,CAAC;IAED;;OAEG;IACI,MAAM,CAAC,QAAQ,CAAC,cAAsB;QAC3C,MAAM,UAAU,GAAgB,4BAAQ,CAAC,eAAe,CACtD,cAAc,EACd,gBAAgB,CAAC,UAAU,CAC5B,CAAC;QAEF,OAAO,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC,CAAC;IACxE,CAAC;;AAjDH,4CAkDC;AAxCC;;GAEG;AACoB,2BAAU,GAAe,8BAAU,CAAC,QAAQ,CACjE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,4BAA4B,CAAC,CACpE,CAAC;AAEF;;GAEG;AACoB,yBAAQ,GAAW,qBAAqB,CAAC"}

package/dist/documenters/IConfigFile.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2020 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Typescript interface describing the config schema for toc.yml file format.
+ */
+export interface IConfigTableOfContents {
+    /**
+     * Optional category name that is recommended to be included along with
+     * one of the configs: {@link IConfigTableOfContents.categorizeByName} or
+     * {@link IConfigTableOfContents.categoryInlineTag}.
+     * Any items that are not matched according to the mentioned configuration options will be placed under this
+     * catchAll category. If none provided the items will not be included in the final toc.yml file.
+     */
+    catchAllCategory?: string;
+    /**
+     * Toggle either categorization of the API items should be made based on category name presence
+     * in the API item's name. Useful when there are API items without an inline tag to categorize them,
+     * but still need to place the items under categories. Note: this type of categorization might place some items
+     * under wrong categories if the names are similar but belong to different categories.
+     * In case that {@link IConfigTableOfContents.categoryInlineTag} is provided it will try categorize by
+     * using it and only if it didn't, it will attempt to categorize by name.
+     */
+    categorizeByName?: boolean;
+    /**
+     * Inline tag that will be used to categorize the API items. Will take precedence over the
+     * {@link IConfigTableOfContents.categorizeByName} flag in trying to place the API item according to the
+     * custom inline tag present in documentation of the source code.
+     */
+    categoryInlineTag?: string;
+    /**
+     * Array of node names that might have already items injected at the time of creating the
+     * {@link IConfigTableOfContents.tocConfig} tree structure but are still needed to be included as category
+     * nodes where API items will be pushed during the categorization algorithm.
+     */
+    nonEmptyCategoryNodeNames?: string[];
+}
+/**
+ * Describes plugin packages to be loaded, and which features to enable.
+ */
+export interface IConfigPlugin {
+    /**
+     * Specifies the name of an API Documenter plugin package to be loaded.  By convention, the NPM package name
+     * should have the prefix `doc-plugin-`.  Its main entry point should export an object named
+     * `apiDocumenterPluginManifest` which implements the {@link IApiDocumenterPluginManifest} interface.
+     */
+    packageName: string;
+    /**
+     * A list of features to be enabled.  The features are defined in {@link IApiDocumenterPluginManifest.features}.
+     * The `enabledFeatureNames` strings are matched with {@link IFeatureDefinition.featureName}.
+     */
+    enabledFeatureNames: string[];
+}
+/**
+ * This interface represents the api-documenter.json file format.
+ */
+export interface IConfigFile {
+    /**
+     * Specifies the output target.
+     */
+    outputTarget: 'docfx' | 'markdown';
+    /**
+     * Specifies what type of newlines API Documenter should use when writing output files.
+     *
+     * @remarks
+     * By default, the output files will be written with Windows-style newlines.
+     * To use POSIX-style newlines, specify "lf" instead.
+     * To use the OS's default newline kind, specify "os".
+     */
+    newlineKind?: 'crlf' | 'lf' | 'os';
+    /**
+     * This enables an experimental feature that will be officially released with the next major version
+     * of API Documenter.  It requires DocFX 2.46 or newer.  It enables documentation for namespaces and
+     * adds them to the table of contents.  This will also affect file layout as namespaced items will be nested
+     * under a directory for the namespace instead of just within the package.
+     *
+     * This setting currently only affects the 'docfx' output target.  It is equivalent to the `--new-docfx-namespaces`
+     * command-line parameter.
+     */
+    newDocfxNamespaces?: boolean;
+    /** {@inheritDoc IConfigPlugin} */
+    plugins?: IConfigPlugin[];
+    /** {@inheritDoc IConfigTableOfContents} */
+    tableOfContents?: IConfigTableOfContents;
+}