@microsoft/api-documenter
Version:
Read JSON files from api-extractor, generate documentation pages
139 lines • 6.12 kB
JavaScript
;
// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
Object.defineProperty(exports, "__esModule", { value: true });
exports.OfficeYamlDocumenter = void 0;
const path = __importStar(require("path"));
const yaml = require("js-yaml");
const node_core_library_1 = require("@rushstack/node-core-library");
const terminal_1 = require("@rushstack/terminal");
const YamlDocumenter_1 = require("./YamlDocumenter");
/**
* Extends YamlDocumenter with some custom logic that is specific to Office Add-ins.
*/
class OfficeYamlDocumenter extends YamlDocumenter_1.YamlDocumenter {
constructor(apiModel, inputFolder, newDocfxNamespaces) {
super(apiModel, newDocfxNamespaces);
// Default API Set URL when no product match is found.
this._apiSetUrlDefault = '/office/dev/add-ins/reference/javascript-api-for-office';
// Hash set of API Set URLs based on product.
this._apiSetUrls = {
Excel: '/javascript/api/requirement-sets/excel/excel-api-requirement-sets',
OneNote: '/javascript/api/requirement-sets/onenote/onenote-api-requirement-sets',
Outlook: '/javascript/api/requirement-sets/outlook/outlook-api-requirement-sets',
PowerPoint: '/javascript/api/requirement-sets/powerpoint/powerpoint-api-requirement-sets',
Visio: '/office/dev/add-ins/reference/overview/visio-javascript-reference-overview',
Word: '/javascript/api/requirement-sets/word/word-api-requirement-sets'
};
const snippetsFilePath = path.join(inputFolder, 'snippets.yaml');
console.log('Loading snippets from ' + snippetsFilePath);
const snippetsContent = node_core_library_1.FileSystem.readFile(snippetsFilePath);
this._snippets = yaml.load(snippetsContent, { filename: snippetsFilePath });
this._snippetsAll = yaml.load(snippetsContent, { filename: snippetsFilePath });
}
/** @override */
generateFiles(outputFolder) {
super.generateFiles(outputFolder);
// After we generate everything, check for any unused snippets
console.log();
for (const apiName of Object.keys(this._snippets)) {
console.error(terminal_1.Colorize.yellow('Warning: Unused snippet ' + apiName));
}
}
/** @override */
onGetTocRoot() {
return {
name: 'API reference',
href: 'overview.md',
items: []
};
}
/** @override */
onCustomizeYamlItem(yamlItem) {
const nameWithoutPackage = yamlItem.uid.replace(/^[^.]+\!/, '');
if (yamlItem.summary) {
yamlItem.summary = this._fixupApiSet(yamlItem.summary, yamlItem.uid);
}
if (yamlItem.remarks) {
yamlItem.remarks = this._fixupApiSet(yamlItem.remarks, yamlItem.uid);
}
const snippets = this._snippetsAll[nameWithoutPackage];
if (snippets) {
delete this._snippets[nameWithoutPackage];
const snippetText = this._generateExampleSnippetText(snippets);
if (yamlItem.remarks) {
yamlItem.remarks += snippetText;
}
else if (yamlItem.syntax && yamlItem.syntax.return) {
if (!yamlItem.syntax.return.description) {
yamlItem.syntax.return.description = '';
}
yamlItem.syntax.return.description += snippetText;
}
else {
yamlItem.remarks = snippetText;
}
}
}
_fixupApiSet(markup, uid) {
// Search for a pattern such as this:
// \[Api set: ExcelApi 1.1\]
//
// Hyperlink it like this:
// \[ [API set: ExcelApi 1.1](http://bing.com?type=excel) \]
markup = markup.replace(/Api/, 'API');
return markup.replace(/\\\[(API set:[^\]]+)\\\]/, '\\[ [$1](' + this._getApiSetUrl(uid) + ') \\]');
}
// Gets the link to the API set based on product context. Seeks a case-insensitive match in the hash set.
_getApiSetUrl(uid) {
for (const key of Object.keys(this._apiSetUrls)) {
const regexp = new RegExp(key, 'i');
if (regexp.test(uid)) {
return this._apiSetUrls[key];
}
}
return this._apiSetUrlDefault; // match not found.
}
_generateExampleSnippetText(snippets) {
const text = ['\n\n#### Examples\n'];
for (const snippet of snippets) {
text.push(`\`\`\`TypeScript\n${snippet}\n\`\`\``);
}
return text.join('\n');
}
}
exports.OfficeYamlDocumenter = OfficeYamlDocumenter;
//# sourceMappingURL=OfficeYamlDocumenter.js.map