From 8e4172ba28381fd20eaa598234c63186631fd6fc Mon Sep 17 00:00:00 2001 From: Matt Mayer <152770+matthewmayer@users.noreply.github.com> Date: Wed, 20 Sep 2023 02:47:34 +0700 Subject: docs: show examples for modules (#2406) Co-authored-by: ST-DDT --- scripts/apidoc/apiDocsWriter.ts | 8 ++++++++ scripts/apidoc/fakerClass.ts | 3 ++- scripts/apidoc/fakerUtilities.ts | 9 ++++++++- scripts/apidoc/markdown.ts | 10 ++++++++++ scripts/apidoc/moduleMethods.ts | 10 +++++++++- scripts/apidoc/signature.ts | 14 ++++++-------- scripts/apidoc/typedoc.ts | 14 +++++++++++++- 7 files changed, 56 insertions(+), 12 deletions(-) (limited to 'scripts') diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts index fe8f48c5..a736bd15 100644 --- a/scripts/apidoc/apiDocsWriter.ts +++ b/scripts/apidoc/apiDocsWriter.ts @@ -37,6 +37,7 @@ editLink: false * @param moduleName The name of the module to write the docs for. * @param lowerModuleName The lowercase name of the module. * @param comment The module comments. + * @param examples The example code. * @param deprecated The deprecation message. * @param methods The methods of the module. */ @@ -44,6 +45,7 @@ export async function writeApiDocsModule( moduleName: string, lowerModuleName: string, comment: string, + examples: string | undefined, deprecated: string | undefined, methods: Method[] ): Promise { @@ -51,6 +53,7 @@ export async function writeApiDocsModule( moduleName, lowerModuleName, comment, + examples, deprecated, methods ); @@ -83,12 +86,15 @@ export async function writeApiDocsModule( * @param moduleName The name of the module to write the docs for. * @param lowerModuleName The lowercase name of the module. * @param comment The module comments. + * @param examples The example code. + * @param deprecated The deprecation message. * @param methods The methods of the module. */ async function writeApiDocsModulePage( moduleName: string, lowerModuleName: string, comment: string, + examples: string | undefined, deprecated: string | undefined, methods: Method[] ): Promise { @@ -118,6 +124,8 @@ async function writeApiDocsModulePage( ${comment} + ${examples == null ? '' : `
${examples}
`} + ::: ${methods diff --git a/scripts/apidoc/fakerClass.ts b/scripts/apidoc/fakerClass.ts index 5ce3c063..d7206cf8 100644 --- a/scripts/apidoc/fakerClass.ts +++ b/scripts/apidoc/fakerClass.ts @@ -29,7 +29,7 @@ async function processClass( console.log(`Processing ${name} class`); - const { comment, deprecated } = analyzeModule(fakerClass); + const { comment, deprecated, examples } = analyzeModule(fakerClass); const methods: Method[] = []; console.debug(`- constructor`); @@ -43,6 +43,7 @@ async function processClass( name, moduleFieldName, comment, + examples, deprecated, methods ); diff --git a/scripts/apidoc/fakerUtilities.ts b/scripts/apidoc/fakerUtilities.ts index 59dadeba..d164857b 100644 --- a/scripts/apidoc/fakerUtilities.ts +++ b/scripts/apidoc/fakerUtilities.ts @@ -28,5 +28,12 @@ async function processUtilities( ) ); - return writeApiDocsModule('Utilities', 'utils', comment, undefined, methods); + return writeApiDocsModule( + 'Utilities', + 'utils', + comment, + undefined, + undefined, + methods + ); } diff --git a/scripts/apidoc/markdown.ts b/scripts/apidoc/markdown.ts index 1ddd433e..7d44fc39 100644 --- a/scripts/apidoc/markdown.ts +++ b/scripts/apidoc/markdown.ts @@ -45,6 +45,16 @@ function comparableSanitizedHtml(html: string): string { .replace(/'/g, "'"); } +/** + * Converts a Typescript code block to an HTML string and sanitizes it. + * @param code The code to convert. + * @returns The converted HTML string. + */ +export function codeToHtml(code: string): string { + const delimiter = '```'; + return mdToHtml(`${delimiter}ts\n${code}\n${delimiter}`); +} + /** * Converts Markdown to an HTML string and sanitizes it. * @param md The markdown to convert. diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index 359282dc..89f234db 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -5,10 +5,12 @@ import type { } from 'typedoc'; import type { Method } from '../../docs/.vitepress/components/api-docs/method'; import { writeApiDocsModule } from './apiDocsWriter'; +import { codeToHtml } from './markdown'; import { analyzeSignature } from './signature'; import { extractDeprecated, extractDescription, + extractJoinedRawExamples, extractModuleFieldName, extractModuleName, selectApiMethodSignatures, @@ -41,7 +43,7 @@ async function processModule( const moduleName = extractModuleName(module); console.log(`Processing Module ${moduleName}`); const moduleFieldName = extractModuleFieldName(module); - const { comment, deprecated } = analyzeModule(module); + const { comment, deprecated, examples } = analyzeModule(module); const methods = await processModuleMethods( module, `faker.${moduleFieldName}.` @@ -51,6 +53,7 @@ async function processModule( moduleName, moduleFieldName, comment, + examples, deprecated, methods ); @@ -65,10 +68,15 @@ async function processModule( export function analyzeModule(module: DeclarationReflection): { comment: string; deprecated: string | undefined; + examples: string | undefined; } { + const examplesRaw = extractJoinedRawExamples(module); + const examples = examplesRaw ? codeToHtml(examplesRaw) : undefined; + return { comment: adjustUrls(extractDescription(module)), deprecated: extractDeprecated(module), + examples, }; } diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index ea39f51b..2cba4904 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -14,12 +14,12 @@ import type { MethodParameter, } from '../../docs/.vitepress/components/api-docs/method'; import { formatTypescript } from './format'; -import { mdToHtml } from './markdown'; +import { codeToHtml, mdToHtml } from './markdown'; import { extractDeprecated, extractDescription, + extractJoinedRawExamples, extractRawDefault, - extractRawExamples, extractSeeAlsos, extractSince, extractSourcePath, @@ -28,8 +28,6 @@ import { toBlock, } from './typedoc'; -const code = '```'; - export async function analyzeSignature( signature: SignatureReflection, accessor: string, @@ -74,9 +72,9 @@ export async function analyzeSignature( let examples = `${accessor}${methodName}${signatureTypeParametersString}(${signatureParametersString}): ${signature.type?.toString()}\n`; - const exampleTags = extractRawExamples(signature); - if (exampleTags.length > 0) { - examples += `${exampleTags.join('\n').trim()}\n`; + const exampleTags = extractJoinedRawExamples(signature); + if (exampleTags) { + examples += exampleTags; } const seeAlsos = extractSeeAlsos(signature).map((seeAlso) => @@ -97,7 +95,7 @@ export async function analyzeSignature( sourcePath: extractSourcePath(signature), throws, returns: await typeToText(signature.type), - examples: mdToHtml(`${code}ts\n${examples}${code}`), + examples: codeToHtml(examples), deprecated, seeAlsos, }; diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index 2e86f2c2..268ae1f4 100644 --- a/scripts/apidoc/typedoc.ts +++ b/scripts/apidoc/typedoc.ts @@ -244,10 +244,22 @@ export function extractRawDefault(reflection?: CommentHolder): string { * * @param reflection The reflection to extract the examples from. */ -export function extractRawExamples(reflection?: CommentHolder): string[] { +function extractRawExamples(reflection?: CommentHolder): string[] { return extractRawCode('@example', reflection); } +/** + * Extracts the examples from the jsdocs without the surrounding md code block, then joins them with newlines and trims. + * + * @param reflection The reflection to extract the examples from. + */ +export function extractJoinedRawExamples( + reflection?: CommentHolder +): string | undefined { + const examples = extractRawExamples(reflection); + return examples.length === 0 ? undefined : examples.join('\n').trim(); +} + /** * Extracts all the `@see` references from the jsdocs separately. * -- cgit v1.2.3