/* 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; } }