diff options
| -rw-r--r-- | scripts/apidoc/apiDocsWriter.ts | 8 | ||||
| -rw-r--r-- | scripts/apidoc/fakerClass.ts | 3 | ||||
| -rw-r--r-- | scripts/apidoc/fakerUtilities.ts | 9 | ||||
| -rw-r--r-- | scripts/apidoc/markdown.ts | 10 | ||||
| -rw-r--r-- | scripts/apidoc/moduleMethods.ts | 10 | ||||
| -rw-r--r-- | scripts/apidoc/signature.ts | 14 | ||||
| -rw-r--r-- | scripts/apidoc/typedoc.ts | 14 | ||||
| -rw-r--r-- | test/scripts/apidoc/__snapshots__/module.spec.ts.snap | 12 | ||||
| -rw-r--r-- | test/scripts/apidoc/module.example.ts | 8 | ||||
| -rw-r--r-- | test/scripts/apidoc/verify-jsdoc-tags.spec.ts | 6 |
10 files changed, 79 insertions, 15 deletions
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<ModuleSummary> { @@ -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<void> { @@ -118,6 +124,8 @@ async function writeApiDocsModulePage( ${comment} + ${examples == null ? '' : `<div class="examples">${examples}</div>`} + ::: ${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 @@ -46,6 +46,16 @@ function comparableSanitizedHtml(html: string): string { } /** + * 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. * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`. 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,11 +244,23 @@ 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. * * @param reflection The reflection to extract the see also references from. diff --git a/test/scripts/apidoc/__snapshots__/module.spec.ts.snap b/test/scripts/apidoc/__snapshots__/module.spec.ts.snap index b3584e13..a7a2ec01 100644 --- a/test/scripts/apidoc/__snapshots__/module.spec.ts.snap +++ b/test/scripts/apidoc/__snapshots__/module.spec.ts.snap @@ -1,10 +1,20 @@ // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html +exports[`module > analyzeModule() > ModuleExampleTest 1`] = ` +{ + "comment": "This is a description for a module with a code example", + "deprecated": undefined, + "examples": "<div class=\\"language-ts\\"><button title=\\"Copy Code\\" class=\\"copy\\"></button><span class=\\"lang\\">ts</span><pre v-pre class=\\"shiki material-theme-palenight\\"><code><span class=\\"line\\"><span style=\\"color:#89DDFF\\">new</span><span style=\\"color:#BABED8\\"> </span><span style=\\"color:#82AAFF\\">ModuleExampleTest</span><span style=\\"color:#BABED8\\">()</span></span></code></pre> +</div>", +} +`; + exports[`module > analyzeModule() > ModuleFakerJsLinkTest 1`] = ` { "comment": "Description with a link to our [website](/) and [api docs](/api/).", "deprecated": undefined, + "examples": undefined, } `; @@ -13,11 +23,13 @@ exports[`module > analyzeModule() > ModuleNextFakerJsLinkTest 1`] = ` "comment": "Description with a link to our [website](/) and [api docs](/api/).", "deprecated": undefined, + "examples": undefined, } `; exports[`module > analyzeModule() > expected and actual modules are equal 1`] = ` [ + "ModuleExampleTest", "ModuleFakerJsLinkTest", "ModuleNextFakerJsLinkTest", ] diff --git a/test/scripts/apidoc/module.example.ts b/test/scripts/apidoc/module.example.ts index ef646659..9671dc73 100644 --- a/test/scripts/apidoc/module.example.ts +++ b/test/scripts/apidoc/module.example.ts @@ -9,3 +9,11 @@ export class ModuleFakerJsLinkTest {} * and [api docs](https://next.fakerjs.dev/api/). */ export class ModuleNextFakerJsLinkTest {} + +/** + * This is a description for a module with a code example + * + * @example + * new ModuleExampleTest() + */ +export class ModuleExampleTest {} diff --git a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts index 557504c8..586605a6 100644 --- a/test/scripts/apidoc/verify-jsdoc-tags.spec.ts +++ b/test/scripts/apidoc/verify-jsdoc-tags.spec.ts @@ -7,8 +7,8 @@ import { analyzeSignature } from '../../../scripts/apidoc/signature'; import { extractDeprecated, extractDescription, + extractJoinedRawExamples, extractModuleFieldName, - extractRawExamples, extractSeeAlsos, extractSince, extractTagContent, @@ -110,7 +110,7 @@ describe('verify JSDoc tags', () => { // Write temp files to disk // Extract examples and make them runnable - const examples = extractRawExamples(signature).join('').trim(); + const examples = extractJoinedRawExamples(signature); // Save examples to a file to run them later in the specific tests const dir = resolveDirToModule(moduleName); @@ -135,7 +135,7 @@ describe('verify JSDoc tags', () => { it('verify @example tag', async () => { // Extract the examples - const examples = extractRawExamples(signature).join('').trim(); + const examples = extractJoinedRawExamples(signature); expect( examples, |