diff --git a/docs/.vitepress/components/api-docs/method.ts b/docs/.vitepress/components/api-docs/method.ts index b58f435e04b..52cb24957bf 100644 --- a/docs/.vitepress/components/api-docs/method.ts +++ b/docs/.vitepress/components/api-docs/method.ts @@ -7,6 +7,7 @@ export interface Method { readonly examples: string; // HTML readonly deprecated: boolean; readonly since: string; + readonly sourcePath: string; // URL-Suffix readonly seeAlsos: string[]; } diff --git a/docs/.vitepress/components/api-docs/method.vue b/docs/.vitepress/components/api-docs/method.vue index c43e5868144..8bff111f36a 100644 --- a/docs/.vitepress/components/api-docs/method.vue +++ b/docs/.vitepress/components/api-docs/method.vue @@ -2,6 +2,7 @@ import type { Method } from './method'; import MethodParameters from './method-parameters.vue'; import { slugify } from '../../shared/utils/slugify'; +import { sourceBaseUrl } from '../../../api/source-base-url'; const props = defineProps<{ method: Method }>(); @@ -20,11 +21,9 @@ function seeAlsoToUrl(see: string): string {
-
-

- Available since v -

-
+

+ Available since v{{ props.method.since }} +

+ +
+

Source

+ +
+ + diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts index d40dec34359..146c79235aa 100644 --- a/scripts/apidoc/apiDocsWriter.ts +++ b/scripts/apidoc/apiDocsWriter.ts @@ -6,6 +6,7 @@ import type { APIGroup, APIItem } from '../../docs/api/api-types'; import { formatMarkdown, formatTypescript } from './format'; import { extractModuleName, + extractSourceBaseUrl, selectApiMethods, selectApiModules, } from './typedoc'; @@ -120,10 +121,20 @@ export function writeApiPagesIndex(pages: PageIndex): void { writeFileSync(pathDocsApiPages, apiPagesContent); } +/** + * Writes the api diff index to the correct location. + * + * @param diffIndex The diff index project to write. + */ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void { writeFileSync(pathDocsDiffIndexFile, JSON.stringify(diffIndex)); } +/** + * Writes the api search index to the correct location. + * + * @param project The typedoc project. + */ export function writeApiSearchIndex(project: ProjectReflection): void { const apiIndex: APIGroup[] = []; @@ -154,3 +165,22 @@ export function writeApiSearchIndex(project: ProjectReflection): void { writeFileSync(pathDocsApiSearchIndex, JSON.stringify(apiIndex)); } + +/** + * Writes the source base url to the correct location. + * + * @param project The typedoc project. + */ +export function writeSourceBaseUrl(project: ProjectReflection): void { + const baseUrl = extractSourceBaseUrl(project); + + let content = ` + // This file is automatically generated. + // Run '${scriptCommand}' to update + export const sourceBaseUrl = '${baseUrl}'; + `.replace(/\n +/, '\n'); + + content = formatTypescript(content); + + writeFileSync(resolve(pathOutputDir, 'source-base-url.ts'), content); +} diff --git a/scripts/apidoc/generate.ts b/scripts/apidoc/generate.ts index 6aa3ae0c7eb..b5ccb3f34d7 100644 --- a/scripts/apidoc/generate.ts +++ b/scripts/apidoc/generate.ts @@ -3,6 +3,7 @@ import { writeApiDiffIndex, writeApiPagesIndex, writeApiSearchIndex, + writeSourceBaseUrl, } from './apiDocsWriter'; import { processModuleMethods } from './moduleMethods'; import { loadProject } from './typedoc'; @@ -26,4 +27,5 @@ export async function generate(): Promise { ); writeApiSearchIndex(project); + writeSourceBaseUrl(project); } diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index bf7b93f91f7..b89e873ca44 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -9,7 +9,7 @@ import { selectApiModules, } from './typedoc'; import type { PageAndDiffIndex } from './utils'; -import { diffHash } from './utils'; +import { diffHash, methodDiffHash } from './utils'; /** * Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`. @@ -62,7 +62,7 @@ function processModuleMethod(module: DeclarationReflection): PageAndDiffIndex { diff: methods.reduce( (data, method) => ({ ...data, - [method.name]: diffHash(method), + [method.name]: methodDiffHash(method), }), { moduleHash: diffHash({ diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index a4b384a9450..9cdd7924fc8 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -23,12 +23,15 @@ import { extractRawExamples, extractSeeAlsos, extractSince, + extractSourcePath, isDeprecated, joinTagParts, } from './typedoc'; import { pathOutputDir } from './utils'; -export function prettifyMethodName(method: string): string { +const code = '```'; + +function prettifyMethodName(method: string): string { return ( // Capitalize and insert space before upper case characters method.substring(0, 1).toUpperCase() + @@ -176,15 +179,13 @@ export function analyzeSignature( mdToHtml(seeAlso, true) ); - const prettyMethodName = prettifyMethodName(methodName); - const code = '```'; - return { name: methodName, - title: prettyMethodName, + title: prettifyMethodName(methodName), description: mdToHtml(toBlock(signature.comment)), parameters: parameters, since: extractSince(signature), + sourcePath: extractSourcePath(signature), returns: typeToText(signature.type), examples: mdToHtml(`${code}ts\n${examples}${code}`), deprecated: isDeprecated(signature), diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index 0ff0906e327..cc5132a9a07 100644 --- a/scripts/apidoc/typedoc.ts +++ b/scripts/apidoc/typedoc.ts @@ -3,6 +3,7 @@ import type { CommentTag, DeclarationReflection, ProjectReflection, + Reflection, SignatureReflection, TypeDocOptions, } from 'typedoc'; @@ -144,6 +145,40 @@ export function extractModuleFieldName(module: DeclarationReflection): string { return moduleName.substring(0, 1).toLowerCase() + moduleName.substring(1); } +/** + * Extracts the source url from the jsdocs. + * + * @param reflection The reflection instance to extract the source url from. + */ +function extractSourceUrl(reflection: Reflection): string { + const source = reflection.sources?.[0]; + return source?.url ?? ''; +} + +/** + * Extracts the source base url from the jsdocs. + * + * @param reflection The reflection instance to extract the source base url from. + */ +export function extractSourceBaseUrl(reflection: Reflection): string { + return extractSourceUrl(reflection).replace( + /^(.*\/blob\/[0-9a-f]+\/)(.*)$/, + '$1' + ); +} + +/** + * Extracts the relative source path from the jsdocs. + * + * @param reflection The reflection instance to extract the source path from. + */ +export function extractSourcePath(reflection: Reflection): string { + return extractSourceUrl(reflection).replace( + /^(.*\/blob\/[0-9a-f]+\/)(.*)$/, + '$2' + ); +} + /** * Extracts the text (md) from a jsdoc tag. * diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts index 5de80cc3c5b..4c9c322d7cf 100644 --- a/scripts/apidoc/utils.ts +++ b/scripts/apidoc/utils.ts @@ -1,5 +1,6 @@ import { createHash } from 'node:crypto'; import { resolve } from 'node:path'; +import type { Method } from '../../docs/.vitepress/components/api-docs/method'; // Types @@ -53,6 +54,18 @@ export function mapByName( ); } +/** + * Creates a diff hash for the given method by removing the line number from the source path. + * + * @param method The method to create a hash for. + */ +export function methodDiffHash(method: Method): string { + return diffHash({ + ...method, + sourcePath: method.sourcePath.replace(/#.*/g, ''), + }); +} + /** * Creates a diff hash for the given object. * diff --git a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap index 66886029090..cb8ff8828d3 100644 --- a/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap +++ b/test/scripts/apidoc/__snapshots__/signature.spec.ts.snap @@ -44,6 +44,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = ` "returns": "T", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L295", "title": "Complex Array Parameter", } `; @@ -69,6 +70,7 @@ exports[`signature > analyzeSignature() > defaultBooleanParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L99", "title": "Default Boolean Param Method", } `; @@ -117,6 +119,7 @@ exports[`signature > analyzeSignature() > functionParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L119", "title": "Function Param Method", } `; @@ -177,6 +180,7 @@ exports[`signature > analyzeSignature() > literalUnionParamMethod 1`] = ` "returns": "string", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L142", "title": "Literal Union Param Method", } `; @@ -196,6 +200,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = ` "test.apidoc.methodWithExample()", ], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L254", "title": "Method With Deprecated", } `; @@ -214,6 +219,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L243", "title": "Method With Example", } `; @@ -234,6 +240,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = ` "test.apidoc.methodWithDeprecated()", ], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L264", "title": "Method With Multiple See Markers", } `; @@ -254,6 +261,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic "test.apidoc.methodWithDeprecated() with parameter bar and baz.", ], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L274", "title": "Method With Multiple See Markers And Backticks", } `; @@ -271,6 +279,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = ` "returns": "number", "seeAlsos": [], "since": "1.0.0", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L283", "title": "Method With Since Marker", } `; @@ -310,6 +319,7 @@ exports[`signature > analyzeSignature() > multiParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L110", "title": "Multi Param Method", } `; @@ -327,6 +337,7 @@ exports[`signature > analyzeSignature() > noParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L72", "title": "No Param Method", } `; @@ -352,6 +363,7 @@ exports[`signature > analyzeSignature() > optionalStringParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L90", "title": "Optional String Param Method", } `; @@ -420,6 +432,7 @@ It also has a more complex description.

"returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L193", "title": "Options Inline Param Method With Defaults", } `; @@ -459,6 +472,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L229", "title": "Options Interface Param Method With Defaults", } `; @@ -517,6 +531,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L169", "title": "Options Param Method", } `; @@ -556,6 +571,7 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`] "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L211", "title": "Options Type Param Method With Defaults", } `; @@ -581,6 +597,7 @@ exports[`signature > analyzeSignature() > requiredNumberParamMethod 1`] = ` "returns": "number", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L81", "title": "Required Number Param Method", } `; @@ -606,6 +623,7 @@ exports[`signature > analyzeSignature() > stringUnionParamMethod 1`] = ` "returns": "string", "seeAlsos": [], "since": "", + "sourcePath": "test/scripts/apidoc/signature.example.ts#L128", "title": "String Union Param Method", } `; diff --git a/test/setup.ts b/test/setup.ts new file mode 100644 index 00000000000..23d693a315d --- /dev/null +++ b/test/setup.ts @@ -0,0 +1,3 @@ +import { chai } from 'vitest'; + +chai.config.truncateThreshold = 10000; diff --git a/vite.config.ts b/vite.config.ts index 169c433815d..cb3a67e3029 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -8,6 +8,7 @@ console.log('VITEST_SEQUENCE_SEED', VITEST_SEQUENCE_SEED); // https://vitejs.dev/config/ export default defineConfig({ test: { + setupFiles: ['test/setup.ts'], coverage: { all: true, reporter: ['clover', 'cobertura', 'lcov', 'text'],