/* eslint-disable no-console */
import fs from 'fs-extra';
import path from 'path';
import { HeritageClause } from 'typescript';
import { assertNever } from '../../packages/common/src/shared-utils';
import { generateFrontMatter } from './docgen-utils';
import {
ClassInfo,
DeclarationInfo,
DocsPage,
EnumInfo,
FunctionInfo,
InterfaceInfo,
MethodParameterInfo,
TypeAliasInfo,
TypeMap,
VariableInfo,
} from './typescript-docgen-types';
const INDENT = ' ';
export class TypescriptDocsRenderer {
render(pages: DocsPage[], docsUrl: string, outputPath: string, typeMap: TypeMap): number {
let generatedCount = 0;
if (!fs.existsSync(outputPath)) {
fs.ensureDirSync(outputPath);
}
for (const page of pages) {
let markdown = '';
markdown += generateFrontMatter(page.title);
const declarationsByWeight = page.declarations.sort((a, b) => a.weight - b.weight);
for (const info of declarationsByWeight) {
switch (info.kind) {
case 'interface':
markdown += this.renderInterfaceOrClass(info, typeMap, docsUrl);
break;
case 'typeAlias':
markdown += this.renderTypeAlias(info, typeMap, docsUrl);
break;
case 'class':
markdown += this.renderInterfaceOrClass(info, typeMap, docsUrl);
break;
case 'enum':
markdown += this.renderEnum(info, typeMap, docsUrl);
break;
case 'function':
markdown += this.renderFunction(info, typeMap, docsUrl);
break;
case 'variable':
markdown += this.renderVariable(info, typeMap, docsUrl);
break;
default:
assertNever(info);
}
}
const categoryDir = path.join(outputPath, ...page.category);
if (!fs.existsSync(categoryDir)) {
fs.mkdirsSync(categoryDir);
}
const pathParts = [];
for (const subCategory of page.category) {
pathParts.push(subCategory);
const indexFile = path.join(outputPath, ...pathParts, 'index.md');
const exists = fs.existsSync(indexFile);
const existingContent = exists && fs.readFileSync(indexFile).toString();
const hasActualContent = existingContent && existingContent.includes('isDefaultIndex: false');
if (!exists && !hasActualContent) {
const indexFileContent =
generateFrontMatter(subCategory, true) +
`\n\nimport DocCardList from '@theme/DocCardList';\n\n`;
fs.writeFileSync(indexFile, indexFileContent);
generatedCount++;
}
}
fs.writeFileSync(path.join(categoryDir, page.fileName + '.md'), markdown);
generatedCount++;
}
return generatedCount;
}
/**
* Render the interface to a markdown string.
*/
private renderInterfaceOrClass(
info: InterfaceInfo | ClassInfo,
knownTypeMap: TypeMap,
docsUrl: string,
): string {
const { title, weight, category, description, members } = info;
let output = '';
output += `\n\n## ${title}\n\n`;
output += this.renderGenerationInfoShortcode(info);
output += `${this.renderDescription(description, knownTypeMap, docsUrl)}\n\n`;
output +=
info.kind === 'interface' ? this.renderInterfaceSignature(info) : this.renderClassSignature(info);
if (info.extendsClause) {
output += '* Extends: ';
output += `${this.renderHeritageClause(info.extendsClause, knownTypeMap, docsUrl)}\n`;
}
if (info.kind === 'class' && info.implementsClause) {
output += '* Implements: ';
output += `${this.renderHeritageClause(info.implementsClause, knownTypeMap, docsUrl)}\n`;
}
if (info.members && info.members.length) {
output += '\n
\n';
output += `${this.renderMembers(info, knownTypeMap, docsUrl)}\n`;
output += '\n\n
\n';
}
return output;
}
/**
* Render the type alias to a markdown string.
*/
private renderTypeAlias(typeAliasInfo: TypeAliasInfo, knownTypeMap: TypeMap, docsUrl: string): string {
const { title, weight, description, type, fullText } = typeAliasInfo;
let output = '';
output += `\n\n## ${title}\n\n`;
output += this.renderGenerationInfoShortcode(typeAliasInfo);
output += `${this.renderDescription(description, knownTypeMap, docsUrl)}\n\n`;
output += this.renderTypeAliasSignature(typeAliasInfo);
if (typeAliasInfo.members && typeAliasInfo.members.length) {
output += '\n\n';
output += `${this.renderMembers(typeAliasInfo, knownTypeMap, docsUrl)}\n`;
output += '\n\n
\n';
}
return output;
}
private renderEnum(enumInfo: EnumInfo, knownTypeMap: TypeMap, docsUrl: string): string {
const { title, weight, description, fullText } = enumInfo;
let output = '';
output += `\n\n## ${title}\n\n`;
output += this.renderGenerationInfoShortcode(enumInfo);
output += `${this.renderDescription(description, knownTypeMap, docsUrl)}\n\n`;
output += this.renderEnumSignature(enumInfo);
return output;
}
private renderFunction(functionInfo: FunctionInfo, knownTypeMap: TypeMap, docsUrl: string): string {
const { title, weight, description, fullText, parameters } = functionInfo;
let output = '';
output += `\n\n## ${title}\n\n`;
output += this.renderGenerationInfoShortcode(functionInfo);
output += `${this.renderDescription(description, knownTypeMap, docsUrl)}\n\n`;
output += this.renderFunctionSignature(functionInfo, knownTypeMap);
if (parameters.length) {
output += 'Parameters\n\n';
output += this.renderFunctionParams(parameters, knownTypeMap, docsUrl);
}
return output;
}
private renderVariable(variableInfo: VariableInfo, knownTypeMap: TypeMap, docsUrl: string): string {
const { title, weight, description, fullText } = variableInfo;
let output = '';
output += `\n\n## ${title}\n\n`;
output += this.renderGenerationInfoShortcode(variableInfo);
output += `${this.renderDescription(description, knownTypeMap, docsUrl)}\n\n`;
return output;
}
/**
* Generates a markdown code block string for the interface signature.
*/
private renderInterfaceSignature(interfaceInfo: InterfaceInfo): string {
const { fullText, members } = interfaceInfo;
let output = '';
output += '```ts title="Signature"\n';
output += `interface ${fullText} `;
if (interfaceInfo.extendsClause) {
output += interfaceInfo.extendsClause.getText() + ' ';
}
output += '{\n';
output += members.map(member => `${INDENT}${member.fullText}`).join('\n');
output += '\n}\n';
output += '```\n';
return output;
}
private renderClassSignature(classInfo: ClassInfo): string {
const { fullText, members } = classInfo;
let output = '';
output += '```ts title="Signature"\n';
output += `class ${fullText} `;
if (classInfo.extendsClause) {
output += classInfo.extendsClause.getText() + ' ';
}
if (classInfo.implementsClause) {
output += classInfo.implementsClause.getText() + ' ';
}
output += '{\n';
const renderModifiers = (modifiers: string[]) => (modifiers.length ? modifiers.join(' ') + ' ' : '');
output += members
.map(member => {
if (member.kind === 'method') {
const args = member.parameters.map(p => this.renderParameter(p, p.type)).join(', ');
if (member.fullText === 'constructor') {
return `${INDENT}constructor(${args})`;
} else {
return `${INDENT}${member.fullText}(${args}) => ${member.type};`;
}
} else {
return `${INDENT}${member.fullText}`;
}
})
.join('\n');
output += '\n}\n';
output += '```\n';
return output;
}
private renderTypeAliasSignature(typeAliasInfo: TypeAliasInfo): string {
const { fullText, members, type } = typeAliasInfo;
let output = '';
output += '```ts title="Signature"\n';
output += `type ${fullText} = `;
if (members) {
output += '{\n';
output += members.map(member => `${INDENT}${member.fullText}`).join('\n');
output += '\n}\n';
} else {
output += type.getText() + '\n';
}
output += '```\n';
return output;
}
private renderEnumSignature(enumInfo: EnumInfo): string {
const { fullText, members } = enumInfo;
let output = '';
output += '```ts title="Signature"\n';
output += `enum ${fullText} `;
if (members) {
output += '{\n';
output += members
.map(member => {
let line = member.description ? `${INDENT}// ${member.description}\n` : '';
line += `${INDENT}${member.fullText}`;
return line;
})
.join('\n');
output += '\n}\n';
}
output += '```\n';
return output;
}
private renderFunctionSignature(functionInfo: FunctionInfo, knownTypeMap: TypeMap): string {
const { fullText, parameters, type } = functionInfo;
const args = parameters.map(p => this.renderParameter(p, p.type)).join(', ');
let output = '';
output += '```ts title="Signature"\n';
output += `function ${fullText}(${args}): ${type ? type.getText() : 'void'}\n`;
output += '```\n';
return output;
}
private renderFunctionParams(
params: MethodParameterInfo[],
knownTypeMap: TypeMap,
docsUrl: string,
): string {
let output = '';
for (const param of params) {
const type = this.renderType(param.type, knownTypeMap, docsUrl);
output += `### ${param.name}\n\n`;
output += `\n\n`;
}
return output;
}
private renderMembers(
info: InterfaceInfo | ClassInfo | TypeAliasInfo | EnumInfo,
knownTypeMap: TypeMap,
docsUrl: string,
): string {
const { members, title } = info;
let output = '';
for (const member of members || []) {
let defaultParam = '';
let sinceParam = '';
let experimentalParam = '';
let type = '';
if (member.kind === 'property') {
type = this.renderType(member.type, knownTypeMap, docsUrl);
defaultParam = member.defaultValue
? `default={\`${this.renderType(member.defaultValue, knownTypeMap, docsUrl)}\`} `
: '';
} else {
const args = member.parameters
.map(p => this.renderParameter(p, this.renderType(p.type, knownTypeMap, docsUrl)))
.join(', ');
if (member.fullText === 'constructor') {
type = `(${args}) => ${title}`;
} else {
type = `(${args}) => ${this.renderType(member.type, knownTypeMap, docsUrl)}`;
}
}
if (member.since) {
sinceParam = `since="${member.since}" `;
}
if (member.experimental) {
experimentalParam = 'experimental="true"';
}
output += `\n### ${member.name}\n\n`;
output += `\n\n`;
output += this.renderDescription(member.description, knownTypeMap, docsUrl);
}
return output;
}
private renderHeritageClause(clause: HeritageClause, knownTypeMap: TypeMap, docsUrl: string) {
return (
clause.types
.map(t => `${this.renderType(t.getText(), knownTypeMap, docsUrl)}`)
.join(', ') + '\n\n'
);
}
private renderParameter(p: MethodParameterInfo, typeString: string): string {
return `${p.name}${p.optional ? '?' : ''}: ${typeString}${
p.initializer ? ` = ${p.initializer}` : ''
}`;
}
private renderGenerationInfoShortcode(info: DeclarationInfo): string {
const sourceFile = info.sourceFile.replace(/^\.\.\//, '');
let sinceData = '';
if (info.since) {
sinceData = ` since="${info.since}"`;
}
let experimental = '';
if (info.experimental) {
experimental = ' experimental="true"';
}
return `\n\n`;
}
/**
* This function takes a string representing a type (e.g. "Array") and turns
* and known types (e.g. "ShippingMethod") into hyperlinks.
*/
private renderType(type: string, knownTypeMap: TypeMap, docsUrl: string): string {
let typeText = type
.trim()
// encode HTML entities
.replace(/[\u00A0-\u9999<>\&]/gim, i => '' + i.charCodeAt(0) + ';')
// remove newlines
.replace(/\n/g, ' ');
for (const [key, val] of knownTypeMap) {
const re = new RegExp(`(?!]*>)\\b${key}\\b(?![^<]*<\/a>)`, 'g');
const strippedIndex = val.replace(/\/_index$/, '');
typeText = typeText.replace(re, `${key}`);
}
return typeText;
}
/**
* Replaces any `{@link Foo}` references in the description with hyperlinks.
*/
private renderDescription(description: string, knownTypeMap: TypeMap, docsUrl: string): string {
for (const [key, val] of knownTypeMap) {
const re = new RegExp(`{@link\\s*${key}}`, 'g');
description = description.replace(re, `${key}`);
}
return description;
}
}