@loopback/tsdocs
Version:
A package to generate api docs using Microsoft api-extractor and api-documenter
117 lines (116 loc) • 4.7 kB
JavaScript
;
// Copyright IBM Corp. and LoopBack contributors 2019,2020. All Rights Reserved.
// Node module: @loopback/tsdocs
// This file is licensed under the MIT License.
// License text available at https://opensource.org/licenses/MIT
Object.defineProperty(exports, "__esModule", { value: true });
exports.updateApiDocs = void 0;
const tslib_1 = require("tslib");
const debug_1 = tslib_1.__importDefault(require("debug"));
const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
const path_1 = tslib_1.__importDefault(require("path"));
const helper_1 = require("./helper");
const debug = (0, debug_1.default)('loopback:tsdocs');
/**
* Update markdown files generated by api-documenter to prepend Jekyll metadata
* and generate `apidocs/index.md`.
*
* @param options - Options for api docs
*/
async function updateApiDocs(options = {}) {
options = Object.assign({
rootDir: process.cwd(),
apiDocsGenerationPath: helper_1.DEFAULT_APIDOCS_GENERATION_PATH,
apiDocsExtractionPath: helper_1.DEFAULT_APIDOCS_EXTRACTION_PATH,
generateDefaultPackageDoc: true,
}, options);
const packages = await (0, helper_1.getPackagesWithTsDocs)(options.rootDir);
/* istanbul ignore if */
if (!packages.length)
return;
const packagesByName = {};
for (const pkg of packages) {
packagesByName[(0, helper_1.getUnscopedPackageName)(pkg.name)] = pkg;
}
options.lernaPackages = packagesByName;
const found = await addJekyllMetadata(packages[0].rootPath, options);
if (found) {
// await generateIndex(packages, options);
}
}
exports.updateApiDocs = updateApiDocs;
/**
* Prepend Jekyll metadata to markdown files
*
* @param lernaRootDir - Root directory for the monorepo
* @param options - Options for api docs
*/
async function addJekyllMetadata(lernaRootDir, options) {
var _a;
const apiDocsRoot = path_1.default.join(lernaRootDir, options.apiDocsGenerationPath);
const exists = await fs_extra_1.default.pathExists(apiDocsRoot);
if (!exists) {
console.error('No API docs found at %s.', apiDocsRoot);
return false;
}
const apiFiles = await fs_extra_1.default.readdir(apiDocsRoot);
for (const f of apiFiles) {
/* istanbul ignore if */
if (!f.endsWith('.md'))
continue;
const name = f.replace(/\.md$/, '');
const isPackage = f.match(/^[^\.]+.md$/) && f !== 'index.md';
/* istanbul ignore if */
if (!options.silent) {
// Only print the package level name
if (isPackage) {
console.log('Updating *.md files for %s', name);
}
}
const docFile = path_1.default.join(apiDocsRoot, f);
let doc = await fs_extra_1.default.readFile(docFile, 'utf-8');
const pkgName = name.split('.')[0];
// Calculate the relative uri for the package
let relativeUri = `packages/${pkgName}`;
const pkg = (_a = options.lernaPackages) === null || _a === void 0 ? void 0 : _a[pkgName];
if (pkg != null) {
relativeUri = path_1.default
.relative(pkg.rootPath, pkg.location)
.split(path_1.default.sep) // On Windows, the relative path has `\`
.join('/');
}
const pkgUrl = f === 'index.md'
? 'https://github.com/loopbackio/loopback-next'
: `https://github.com/loopbackio/loopback-next/tree/master/${relativeUri}`;
if (isPackage && options.generateDefaultPackageDoc) {
const modelFile = path_1.default.join(path_1.default.join(lernaRootDir, options.apiDocsExtractionPath, `models/${name}.api.json`));
/**
* "kind": "Package",
* "canonicalReference": "@loopback/authentication",
* "docComment": "",
* "name": "@loopback/authentication",
*/
const model = await fs_extra_1.default.readJson(modelFile, { encoding: 'utf-8' });
debug('Package %s', name, model);
if (model.kind === 'Package' && !model.docComment) {
const pkgDoc = `[${model.name}](${pkgUrl})`;
doc = doc.replace(`## ${name} package`, `## ${name} package\n\n${pkgDoc}`);
}
}
doc = `---
lang: en
title: 'API docs: ${name}'
keywords: LoopBack 4.0, LoopBack 4, Node.js, TypeScript, OpenAPI
sidebar: lb4_sidebar
editurl: ${pkgUrl}
permalink: /doc/en/lb4/apidocs.${name}.html
---
${doc}
`;
if (!options.dryRun) {
await fs_extra_1.default.writeFile(docFile, doc, 'utf-8');
}
}
return true;
}
//# sourceMappingURL=update-api-md-docs.js.map