docs: show source link (#1780)

Co-authored-by: Shinigami92 <[email protected]>

6 files changed, 88 insertions, 7 deletions

diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts
index d40dec34..146c7923 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 6aa3ae0c..b5ccb3f3 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<void> {
   );
 
   writeApiSearchIndex(project);
+  writeSourceBaseUrl(project);
 }
diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts
index bf7b93f9..b89e873c 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 a4b384a9..9cdd7924 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 0ff0906e..cc5132a9 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';
@@ -145,6 +146,40 @@ export function extractModuleFieldName(module: DeclarationReflection): string {
 }
 
 /**
+ * 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.
  *
  * @param tag The tag to extract the text from.
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index 5de80cc3..4c9c322d 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
 
@@ -54,6 +55,18 @@ export function mapByName<T extends { name: string }, V>(
 }
 
 /**
+ * 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.
  *
  * @param object The object to create a hash for.