| 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,oEAA0D;AAI1D,qDAAkD;AAUlD;;GAEG;AACH,MAAa,oBAAqB,SAAQ,+BAAc;IAiBtD,YAAmB,QAAkB,EAAE,WAAmB,EAAE,kBAA4B;QACtF,KAAK,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;QAdtC,sDAAsD;QAC9C,sBAAiB,GAAW,yDAAyD,CAAC;QAE9F,6CAA6C;QACrC,gBAAW,GAA2B;YAC5C,KAAK,EAAE,mEAAmE;YAC1E,OAAO,EAAE,uEAAuE;YAChF,OAAO,EAAE,uEAAuE;YAChF,UAAU,EAAE,6EAA6E;YACzF,KAAK,EAAE,4EAA4E;YACnF,IAAI,EAAE,iEAAiE;SACxE,CAAC;QAKA,MAAM,gBAAgB,GAAW,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;QAEzE,OAAO,CAAC,GAAG,CAAC,wBAAwB,GAAG,gBAAgB,CAAC,CAAC;QAEzD,MAAM,eAAe,GAAW,8BAAU,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;QACtE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,gBAAgB;IACT,aAAa,CAAC,YAAoB;QACvC,KAAK,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;QAElC,8DAA8D;QAC9D,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE;YACjD,OAAO,CAAC,KAAK,CAAC,gBAAM,CAAC,MAAM,CAAC,0BAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;SACpE;IACH,CAAC;IAED,gBAAgB;IACN,YAAY;QACpB,WAAW;QACX,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,IAAI,EAAE,aAAa;YACnB,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAED,gBAAgB;IACN,mBAAmB,CAAC,QAAmB;QAC/C,MAAM,kBAAkB,GAAW,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI,QAAQ,CAAC,OAAO,EAAE;YACpB,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;SACtE;QACD,IAAI,QAAQ,CAAC,OAAO,EAAE;YACpB,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;SACtE;QAED,MAAM,QAAQ,GAAyB,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,CAAC;QAC7E,IAAI,QAAQ,EAAE;YACZ,OAAO,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;YAC1C,MAAM,WAAW,GAAW,IAAI,CAAC,2BAA2B,CAAC,QAAQ,CAAC,CAAC;YACvE,IAAI,QAAQ,CAAC,OAAO,EAAE;gBACpB,QAAQ,CAAC,OAAO,IAAI,WAAW,CAAC;aACjC;iBAAM,IAAI,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;gBACpD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE;oBACvC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;iBACzC;gBACD,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,IAAI,WAAW,CAAC;aACnD;iBAAM;gBACL,QAAQ,CAAC,OAAO,GAAG,WAAW,CAAC;aAChC;SACF;IACH,CAAC;IAEO,YAAY,CAAC,MAAc,EAAE,GAAW;QAC9C,qCAAqC;QACrC,4BAA4B;QAC5B,EAAE;QACF,0BAA0B;QAC1B,4DAA4D;QAC5D,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACtC,OAAO,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IACrG,CAAC;IAED,yGAAyG;IACjG,aAAa,CAAC,GAAW;QAC/B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE;YAC/C,MAAM,MAAM,GAAW,IAAI,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC5C,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;gBACpB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;aAC9B;SACF;QACD,OAAO,IAAI,CAAC,iBAAiB,CAAC,CAAC,mBAAmB;IACpD,CAAC;IAEO,2BAA2B,CAAC,QAAkB;QACpD,MAAM,IAAI,GAAa,CAAC,qBAAqB,CAAC,CAAC;QAC/C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE;YAC9B,IAAI,CAAC,IAAI,CAAC,qBAAqB,OAAO,UAAU,CAAC,CAAC;SACnD;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;CACF;AAzGD,oDAyGC","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 type { ApiModel } from '@microsoft/api-extractor-model';\nimport { FileSystem } from '@rushstack/node-core-library';\n\nimport type { IYamlTocItem } from '../yaml/IYamlTocFile';\nimport type { 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"]} |