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 }}
+
+
+
+
+
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'],