@microsoft/api-documenter 7.21.6 → 7.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -19,7 +19,6 @@ export declare class OfficeYamlDocumenter extends YamlDocumenter {
|
|
|
19
19
|
protected onCustomizeYamlItem(yamlItem: IYamlItem): void;
|
|
20
20
|
private _fixupApiSet;
|
|
21
21
|
private _getApiSetUrl;
|
|
22
|
-
private _fixBoldAndItalics;
|
|
23
22
|
private _generateExampleSnippetText;
|
|
24
23
|
}
|
|
25
24
|
//# sourceMappingURL=OfficeYamlDocumenter.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"OfficeYamlDocumenter.d.ts","sourceRoot":"","sources":["../../src/documenters/OfficeYamlDocumenter.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUlD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,YAAY,CAAgB;IAGpC,OAAO,CAAC,iBAAiB,CAAqE;IAG9F,OAAO,CAAC,WAAW,CAOjB;gBAEiB,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,OAAO;IAYxF,gBAAgB;IACT,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAUhD,gBAAgB;IAChB,SAAS,CAAC,YAAY,IAAI,YAAY;IAStC,gBAAgB;IAChB,SAAS,CAAC,mBAAmB,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;
|
|
1
|
+
{"version":3,"file":"OfficeYamlDocumenter.d.ts","sourceRoot":"","sources":["../../src/documenters/OfficeYamlDocumenter.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAG1D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAUlD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,YAAY,CAAgB;IAGpC,OAAO,CAAC,iBAAiB,CAAqE;IAG9F,OAAO,CAAC,WAAW,CAOjB;gBAEiB,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,OAAO;IAYxF,gBAAgB;IACT,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAUhD,gBAAgB;IAChB,SAAS,CAAC,YAAY,IAAI,YAAY;IAStC,gBAAgB;IAChB,SAAS,CAAC,mBAAmB,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IA0BxD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,2BAA2B;CAOpC"}
|
|
@@ -80,18 +80,9 @@ class OfficeYamlDocumenter extends YamlDocumenter_1.YamlDocumenter {
|
|
|
80
80
|
const nameWithoutPackage = yamlItem.uid.replace(/^[^.]+\!/, '');
|
|
81
81
|
if (yamlItem.summary) {
|
|
82
82
|
yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);
|
|
83
|
-
yamlItem.summary = this._fixBoldAndItalics(yamlItem.summary);
|
|
84
83
|
}
|
|
85
84
|
if (yamlItem.remarks) {
|
|
86
85
|
yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);
|
|
87
|
-
yamlItem.remarks = this._fixBoldAndItalics(yamlItem.remarks);
|
|
88
|
-
}
|
|
89
|
-
if (yamlItem.syntax && yamlItem.syntax.parameters) {
|
|
90
|
-
yamlItem.syntax.parameters.forEach((part) => {
|
|
91
|
-
if (part.description) {
|
|
92
|
-
part.description = this._fixBoldAndItalics(part.description);
|
|
93
|
-
}
|
|
94
|
-
});
|
|
95
86
|
}
|
|
96
87
|
const snippets = this._snippetsAll[nameWithoutPackage];
|
|
97
88
|
if (snippets) {
|
|
@@ -130,20 +121,10 @@ class OfficeYamlDocumenter extends YamlDocumenter_1.YamlDocumenter {
|
|
|
130
121
|
}
|
|
131
122
|
return this._apiSetUrlDefault; // match not found.
|
|
132
123
|
}
|
|
133
|
-
_fixBoldAndItalics(text) {
|
|
134
|
-
return node_core_library_1.Text.replaceAll(text, '\\*', '*');
|
|
135
|
-
}
|
|
136
124
|
_generateExampleSnippetText(snippets) {
|
|
137
125
|
const text = ['\n\n#### Examples\n'];
|
|
138
126
|
for (const snippet of snippets) {
|
|
139
|
-
|
|
140
|
-
text.push('```javascript');
|
|
141
|
-
}
|
|
142
|
-
else {
|
|
143
|
-
text.push('```typescript');
|
|
144
|
-
}
|
|
145
|
-
text.push(snippet);
|
|
146
|
-
text.push('```');
|
|
127
|
+
text.push(`\`\`\`TypeScript\n${snippet}\n\`\`\``);
|
|
147
128
|
}
|
|
148
129
|
return text.join('\n');
|
|
149
130
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"OfficeYamlDocumenter.js","sourceRoot":"","sources":["../../src/documenters/OfficeYamlDocumenter.ts"],"names":[],"mappings":";AAAA,4FAA4F;AAC5F,2DAA2D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE3D,oDAA4B;AAC5B,2CAA6B;AAC7B,gCAAiC;AAGjC,
|
|
1
|
+
{"version":3,"file":"OfficeYamlDocumenter.js","sourceRoot":"","sources":["../../src/documenters/OfficeYamlDocumenter.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.\n// See LICENSE in the project root for license information.\n\nimport colors from 'colors';\nimport * as path from 'path';\nimport yaml = require('js-yaml');\n\nimport { ApiModel } from '@microsoft/api-extractor-model';\nimport { FileSystem } from '@rushstack/node-core-library';\n\nimport { IYamlTocItem } from '../yaml/IYamlTocFile';\nimport { IYamlItem } from '../yaml/IYamlApiFile';\nimport { YamlDocumenter } from './YamlDocumenter';\n\ninterface ISnippetsFile {\n /**\n * The keys are API names like \"Excel.Range.clear\".\n * The values are TypeScript source code excerpts.\n */\n [apiName: string]: string[];\n}\n\n/**\n * Extends YamlDocumenter with some custom logic that is specific to Office Add-ins.\n */\nexport class OfficeYamlDocumenter extends YamlDocumenter {\n private _snippets: ISnippetsFile;\n private _snippetsAll: ISnippetsFile;\n\n // Default API Set URL when no product match is found.\n private _apiSetUrlDefault: string = '/office/dev/add-ins/reference/javascript-api-for-office';\n\n // Hash set of API Set URLs based on product.\n private _apiSetUrls: Record<string, string> = {\n Excel: '/javascript/api/requirement-sets/excel/excel-api-requirement-sets',\n OneNote: '/javascript/api/requirement-sets/onenote/onenote-api-requirement-sets',\n Outlook: '/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets',\n PowerPoint: '/javascript/api/requirement-sets/powerpoint/powerpoint-api-requirement-sets',\n Visio: '/office/dev/add-ins/reference/overview/visio-javascript-reference-overview',\n Word: '/javascript/api/requirement-sets/word/word-api-requirement-sets'\n };\n\n public constructor(apiModel: ApiModel, inputFolder: string, newDocfxNamespaces?: boolean) {\n super(apiModel, newDocfxNamespaces);\n\n const snippetsFilePath: string = path.join(inputFolder, 'snippets.yaml');\n\n console.log('Loading snippets from ' + snippetsFilePath);\n\n const snippetsContent: string = FileSystem.readFile(snippetsFilePath);\n this._snippets = yaml.load(snippetsContent, { filename: snippetsFilePath });\n this._snippetsAll = yaml.load(snippetsContent, { filename: snippetsFilePath });\n }\n\n /** @override */\n public generateFiles(outputFolder: string): void {\n super.generateFiles(outputFolder);\n\n // After we generate everything, check for any unused snippets\n console.log();\n for (const apiName of Object.keys(this._snippets)) {\n console.error(colors.yellow('Warning: Unused snippet ' + apiName));\n }\n }\n\n /** @override */\n protected onGetTocRoot(): IYamlTocItem {\n // override\n return {\n name: 'API reference',\n href: 'overview.md',\n items: []\n };\n }\n\n /** @override */\n protected onCustomizeYamlItem(yamlItem: IYamlItem): void {\n const nameWithoutPackage: string = yamlItem.uid.replace(/^[^.]+\\!/, '');\n if (yamlItem.summary) {\n yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);\n }\n if (yamlItem.remarks) {\n yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);\n }\n\n const snippets: string[] | undefined = this._snippetsAll[nameWithoutPackage];\n if (snippets) {\n delete this._snippets[nameWithoutPackage];\n const snippetText: string = this._generateExampleSnippetText(snippets);\n if (yamlItem.remarks) {\n yamlItem.remarks += snippetText;\n } else if (yamlItem.syntax && yamlItem.syntax.return) {\n if (!yamlItem.syntax.return.description) {\n yamlItem.syntax.return.description = '';\n }\n yamlItem.syntax.return.description += snippetText;\n } else {\n yamlItem.remarks = snippetText;\n }\n }\n }\n\n private _fixupApiSet(markup: string, uid: string): string {\n // Search for a pattern such as this:\n // \\[Api set: ExcelApi 1.1\\]\n //\n // Hyperlink it like this:\n // \\[ [API set: ExcelApi 1.1](http://bing.com?type=excel) \\]\n markup = markup.replace(/Api/, 'API');\n return markup.replace(/\\\\\\[(API set:[^\\]]+)\\\\\\]/, '\\\\[ [$1](' + this._getApiSetUrl(uid) + ') \\\\]');\n }\n\n // Gets the link to the API set based on product context. Seeks a case-insensitive match in the hash set.\n private _getApiSetUrl(uid: string): string {\n for (const key of Object.keys(this._apiSetUrls)) {\n const regexp: RegExp = new RegExp(key, 'i');\n if (regexp.test(uid)) {\n return this._apiSetUrls[key];\n }\n }\n return this._apiSetUrlDefault; // match not found.\n }\n\n private _generateExampleSnippetText(snippets: string[]): string {\n const text: string[] = ['\\n\\n#### Examples\\n'];\n for (const snippet of snippets) {\n text.push(`\\`\\`\\`TypeScript\\n${snippet}\\n\\`\\`\\``);\n }\n return text.join('\\n');\n }\n}\n"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@microsoft/api-documenter",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.22.0",
|
|
4
4
|
"description": "Read JSON files from api-extractor, generate documentation pages",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"@types/resolve": "1.20.2",
|
|
31
31
|
"@rushstack/eslint-config": "3.2.0",
|
|
32
32
|
"@rushstack/heft": "0.50.0",
|
|
33
|
-
"@rushstack/heft-node-rig": "1.12.
|
|
33
|
+
"@rushstack/heft-node-rig": "1.12.6"
|
|
34
34
|
},
|
|
35
35
|
"scripts": {
|
|
36
36
|
"build": "heft build --clean",
|