Skip to content

Commit

Permalink
Merge pull request #1537 from rbuckton/flattenNamespaces2
Browse files Browse the repository at this point in the history
[api-documenter] Include namespaces in YAML output
  • Loading branch information
octogonz authored Nov 24, 2019
2 parents 2257123 + 5f49ef7 commit 625c095
Show file tree
Hide file tree
Showing 24 changed files with 1,670 additions and 245 deletions.
12 changes: 10 additions & 2 deletions apps/api-documenter/src/cli/YamlAction.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import { ApiModel } from '@microsoft/api-extractor-model';

export class YamlAction extends BaseAction {
private _officeParameter: CommandLineFlagParameter;
private _newDocfxNamespacesParameter: CommandLineFlagParameter;

public constructor(parser: ApiDocumenterCommandLine) {
super({
Expand All @@ -32,14 +33,21 @@ export class YamlAction extends BaseAction {
parameterLongName: '--office',
description: `Enables some additional features specific to Office Add-ins`
});
this._newDocfxNamespacesParameter = this.defineFlagParameter({
parameterLongName: '--new-docfx-namespaces',
description: `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.`
});
}

protected onExecute(): Promise<void> { // override
const apiModel: ApiModel = this.buildApiModel();

const yamlDocumenter: YamlDocumenter = this._officeParameter.value
? new OfficeYamlDocumenter(apiModel, this.inputFolder)
: new YamlDocumenter(apiModel);
? new OfficeYamlDocumenter(apiModel, this.inputFolder, this._newDocfxNamespacesParameter.value)
: new YamlDocumenter(apiModel, this._newDocfxNamespacesParameter.value);

yamlDocumenter.generateFiles(this.outputFolder);
return Promise.resolve();
Expand Down
15 changes: 3 additions & 12 deletions apps/api-documenter/src/documenters/ExperimentalYamlDocumenter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
private _catchAllPointer: IYamlTocItem;

public constructor(apiModel: ApiModel, documenterConfig: DocumenterConfig) {
super(apiModel);
super(apiModel, documenterConfig.configFile.newDocfxNamespaces);
this._config = documenterConfig.configFile.tableOfContents!;

this._tocPointerMap = {};
Expand All @@ -37,9 +37,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {
const tocItems: IYamlTocItem[] = [];
for (const apiItem of apiItems) {
let tocItem: IYamlTocItem;

if (apiItem.kind === ApiItemKind.Namespace) {
// Namespaces don't have nodes yet
if (apiItem.kind === ApiItemKind.Namespace && !this.newDocfxNamespaces) {
tocItem = {
name: this._getTocItemName(apiItem)
};
Expand All @@ -61,14 +59,7 @@ export class ExperimentalYamlDocumenter extends YamlDocumenter {

tocItems.push(tocItem);

let children: ReadonlyArray<ApiItem>;
if (apiItem.kind === ApiItemKind.Package) {
// Skip over the entry point, since it's not part of the documentation hierarchy
children = apiItem.members[0].members;
} else {
children = apiItem.members;
}

const children: ApiItem[] = this._getLogicalChildren(apiItem);
const childItems: IYamlTocItem[] = this._buildTocItems2(children);
if (childItems.length > 0) {
tocItem.items = childItems;
Expand Down
11 changes: 11 additions & 0 deletions apps/api-documenter/src/documenters/IConfigFile.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,17 @@ export interface IConfigFile {
*/
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[];

Expand Down
4 changes: 2 additions & 2 deletions apps/api-documenter/src/documenters/OfficeYamlDocumenter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ export class OfficeYamlDocumenter extends YamlDocumenter {
'Word': '/office/dev/add-ins/reference/requirement-sets/word-api-requirement-sets'
};

public constructor(apiModel: ApiModel, inputFolder: string) {
super(apiModel);
public constructor(apiModel: ApiModel, inputFolder: string, newDocfxNamespaces?: boolean) {
super(apiModel, newDocfxNamespaces);

const snippetsFilePath: string = path.join(inputFolder, 'snippets.yaml');

Expand Down
Loading

0 comments on commit 625c095

Please sign in to comment.