diff options
Diffstat (limited to 'scripts')
| -rw-r--r-- | scripts/apidoc.ts | 2 | ||||
| -rw-r--r-- | scripts/apidoc/fakerClass.ts | 6 | ||||
| -rw-r--r-- | scripts/apidoc/markdown.ts | 68 | ||||
| -rw-r--r-- | scripts/apidoc/moduleMethods.ts | 5 | ||||
| -rw-r--r-- | scripts/apidoc/signature.ts | 87 | ||||
| -rw-r--r-- | scripts/apidoc/typedoc.ts | 11 |
6 files changed, 92 insertions, 87 deletions
diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts index ecb1f8fe..31171b9d 100644 --- a/scripts/apidoc.ts +++ b/scripts/apidoc.ts @@ -1,5 +1,5 @@ import { generate } from './apidoc/generate'; -import { initMarkdownRenderer } from './apidoc/signature'; +import { initMarkdownRenderer } from './apidoc/markdown'; async function build(): Promise<void> { await initMarkdownRenderer(); diff --git a/scripts/apidoc/fakerClass.ts b/scripts/apidoc/fakerClass.ts index 9d11815f..c3a5287d 100644 --- a/scripts/apidoc/fakerClass.ts +++ b/scripts/apidoc/fakerClass.ts @@ -3,8 +3,8 @@ import { ReflectionKind } from 'typedoc'; import type { Method } from '../../docs/.vitepress/components/api-docs/method'; import { writeApiDocsModule } from './apiDocsWriter'; import { processModuleMethods } from './moduleMethods'; -import { analyzeSignature, toBlock } from './signature'; -import { selectApiSignature } from './typedoc'; +import { analyzeSignature } from './signature'; +import { extractDescription, selectApiSignature } from './typedoc'; import type { ModuleSummary } from './utils'; export function processFakerClass(project: ProjectReflection): ModuleSummary { @@ -21,7 +21,7 @@ export function processFakerClass(project: ProjectReflection): ModuleSummary { function processClass(fakerClass: DeclarationReflection): ModuleSummary { console.log(`Processing Faker class`); - const comment = toBlock(fakerClass.comment); + const comment = extractDescription(fakerClass); const methods: Method[] = []; console.debug(`- constructor`); diff --git a/scripts/apidoc/markdown.ts b/scripts/apidoc/markdown.ts new file mode 100644 index 00000000..8505b51d --- /dev/null +++ b/scripts/apidoc/markdown.ts @@ -0,0 +1,68 @@ +import sanitizeHtml from 'sanitize-html'; +import type { MarkdownRenderer } from 'vitepress'; +import { createMarkdownRenderer } from 'vitepress'; +import vitepressConfig from '../../docs/.vitepress/config'; +import { pathOutputDir } from './utils'; + +let markdown: MarkdownRenderer; + +export async function initMarkdownRenderer(): Promise<void> { + markdown = await createMarkdownRenderer( + pathOutputDir, + vitepressConfig.markdown, + '/' + ); +} + +const htmlSanitizeOptions: sanitizeHtml.IOptions = { + allowedTags: [ + 'a', + 'button', + 'code', + 'div', + 'li', + 'p', + 'pre', + 'span', + 'strong', + 'ul', + ], + allowedAttributes: { + a: ['href', 'target', 'rel'], + button: ['class', 'title'], + div: ['class'], + pre: ['class', 'tabindex', 'v-pre'], + span: ['class', 'style'], + }, + selfClosing: [], +}; + +function comparableSanitizedHtml(html: string): string { + return html + .replace(/>/g, '>') + .replace(/ /g, '') + .replace(/"/g, '"') + .replace(/'/g, "'"); +} + +/** + * Converts Markdown to an HTML string and sanitizes it. + * @param md The markdown to convert. + * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`. + * @returns The converted HTML string. + */ +export function mdToHtml(md: string, inline: boolean = false): string { + const rawHtml = inline ? markdown.renderInline(md) : markdown.render(md); + + const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions); + // Revert some escaped characters for comparison. + if (comparableSanitizedHtml(rawHtml) === comparableSanitizedHtml(safeHtml)) { + return safeHtml.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/'); + } + + console.debug('Rejected unsafe md:', md); + console.error('Rejected unsafe html:', rawHtml); + console.error('Rejected unsafe html:', comparableSanitizedHtml(rawHtml)); + console.error('Expected safe html:', comparableSanitizedHtml(safeHtml)); + throw new Error('Found unsafe html'); +} diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index 9c902dd7..55b1869f 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -5,9 +5,10 @@ import type { } from 'typedoc'; import type { Method } from '../../docs/.vitepress/components/api-docs/method'; import { writeApiDocsModule } from './apiDocsWriter'; -import { analyzeSignature, stripAbsoluteFakerUrls, toBlock } from './signature'; +import { analyzeSignature } from './signature'; import { extractDeprecated, + extractDescription, extractModuleFieldName, extractModuleName, selectApiMethodSignatures, @@ -35,7 +36,7 @@ function processModule(module: DeclarationReflection): ModuleSummary { const moduleName = extractModuleName(module); const moduleFieldName = extractModuleFieldName(module); console.log(`Processing Module ${moduleName}`); - const comment = stripAbsoluteFakerUrls(toBlock(module.comment)); + const comment = extractDescription(module); const deprecated = extractDeprecated(module); const methods = processModuleMethods(module, `faker.${moduleFieldName}.`); diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 8b5083ae..67101574 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -1,4 +1,3 @@ -import sanitizeHtml from 'sanitize-html'; import type { Comment, DeclarationReflection, @@ -10,16 +9,15 @@ import type { Type, } from 'typedoc'; import { ReflectionFlag, ReflectionKind } from 'typedoc'; -import type { MarkdownRenderer } from 'vitepress'; -import { createMarkdownRenderer } from 'vitepress'; import type { Method, MethodParameter, } from '../../docs/.vitepress/components/api-docs/method'; -import vitepressConfig from '../../docs/.vitepress/config'; import { formatTypescript } from './format'; +import { mdToHtml } from './markdown'; import { extractDeprecated, + extractDescription, extractRawDefault, extractRawExamples, extractSeeAlsos, @@ -27,84 +25,11 @@ import { extractSourcePath, extractThrows, joinTagParts, + toBlock, } from './typedoc'; -import { pathOutputDir } from './utils'; const code = '```'; -export const MISSING_DESCRIPTION = 'Missing'; - -export function toBlock(comment?: Comment): string { - return joinTagParts(comment?.summary) || MISSING_DESCRIPTION; -} - -export function stripAbsoluteFakerUrls(markdown: string): string { - return markdown.replace(/https:\/\/(next.)?fakerjs.dev\//g, '/'); -} - -let markdown: MarkdownRenderer; - -export async function initMarkdownRenderer(): Promise<void> { - markdown = await createMarkdownRenderer( - pathOutputDir, - vitepressConfig.markdown, - '/' - ); -} - -const htmlSanitizeOptions: sanitizeHtml.IOptions = { - allowedTags: [ - 'a', - 'button', - 'code', - 'div', - 'li', - 'p', - 'pre', - 'span', - 'strong', - 'ul', - ], - allowedAttributes: { - a: ['href', 'target', 'rel'], - button: ['class', 'title'], - div: ['class'], - pre: ['class', 'tabindex', 'v-pre'], - span: ['class', 'style'], - }, - selfClosing: [], -}; - -function comparableSanitizedHtml(html: string): string { - return html - .replace(/>/g, '>') - .replace(/ /g, '') - .replace(/"/g, '"') - .replace(/'/g, "'"); -} - -/** - * Converts Markdown to an HTML string and sanitizes it. - * @param md The markdown to convert. - * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`. - * @returns The converted HTML string. - */ -function mdToHtml(md: string, inline: boolean = false): string { - const rawHtml = inline ? markdown.renderInline(md) : markdown.render(md); - - const safeHtml: string = sanitizeHtml(rawHtml, htmlSanitizeOptions); - // Revert some escaped characters for comparison. - if (comparableSanitizedHtml(rawHtml) === comparableSanitizedHtml(safeHtml)) { - return safeHtml; - } - - console.debug('Rejected unsafe md:', md); - console.error('Rejected unsafe html:', rawHtml); - console.error('Rejected unsafe html:', comparableSanitizedHtml(rawHtml)); - console.error('Expected safe html:', comparableSanitizedHtml(safeHtml)); - throw new Error('Found unsafe html'); -} - export function analyzeSignature( signature: SignatureReflection, accessor: string, @@ -120,7 +45,7 @@ export function analyzeSignature( parameters.push({ name: `<${parameter.name}>`, type: parameter.type ? typeToText(parameter.type) : undefined, - description: mdToHtml(toBlock(parameter.comment)), + description: mdToHtml(extractDescription(parameter)), }); } @@ -166,7 +91,7 @@ export function analyzeSignature( return { name: methodName, - description: mdToHtml(toBlock(signature.comment)), + description: mdToHtml(extractDescription(signature)), parameters: parameters, since: extractSince(signature), sourcePath: extractSourcePath(signature), @@ -200,7 +125,7 @@ function analyzeParameter(parameter: ParameterReflection): { name: declarationName, type: typeToText(type, true), default: defaultValue, - description: mdToHtml(toBlock(parameter.comment)), + description: mdToHtml(extractDescription(parameter)), }, ]; parameters.push(...analyzeParameterOptions(name, type)); diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index 858171ac..1a782aa9 100644 --- a/scripts/apidoc/typedoc.ts +++ b/scripts/apidoc/typedoc.ts @@ -1,4 +1,5 @@ import type { + Comment, CommentDisplayPart, CommentTag, DeclarationReflection, @@ -149,6 +150,16 @@ export function extractModuleFieldName(module: DeclarationReflection): string { return moduleName.substring(0, 1).toLowerCase() + moduleName.substring(1); } +export const MISSING_DESCRIPTION = 'Missing'; + +export function toBlock(comment?: Comment): string { + return joinTagParts(comment?.summary) || MISSING_DESCRIPTION; +} + +export function extractDescription(reflection: Reflection): string { + return toBlock(reflection.comment); +} + /** * Extracts the source url from the jsdocs. * |