docs: show source link

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[];
 }
 

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 {
 
     <div v-html="props.method.description"></div>
 
-    <div v-if="props.method.since">
-      <p>
-        <em>Available since v<span v-html="props.method.since" /></em>
-      </p>
-    </div>
+    <p v-if="props.method.since">
+      <em>Available since v{{ props.method.since }}</em>
+    </p>
 
     <MethodParameters
       v-if="props.method.parameters.length > 0"
@@ -48,5 +47,44 @@ function seeAlsoToUrl(see: string): string {
         </li>
       </ul>
     </div>
+
+    <div v-if="props.method.sourcePath">
+      <h3>Source</h3>
+      <ul>
+        <li>
+          <a
+            :href="sourceBaseUrl + props.method.sourcePath"
+            target="_blank"
+            class="source-link"
+          >
+            View Source
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 24 24"
+              fill="currentColor"
+              width="1.2em"
+              height="1.2em"
+              class="source-link-icon"
+            >
+              <path
+                d="M14,3V5H17.59L7.76,14.83L9.17,16.24L19,6.41V10H21V3M19,19H5V5H12V3H5C3.89,3 3,3.9 3,5V19A2,2 0 0,0 5,21H19A2,2 0 0,0 21,19V12H19V19Z"
+              />
+            </svg>
+          </a>
+        </li>
+      </ul>
+    </div>
   </div>
 </template>
+
+<style scoped>
+a.source-link {
+  display: flex;
+  align-items: center;
+}
+
+svg.source-link-icon {
+  display: inline;
+  margin-left: 0.3em;
+}
+</style>

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,6 +121,11 @@ export function writeApiPagesIndex(pages: PageIndex): void {
   writeFileSync(pathDocsApiPages, apiPagesContent);
 }
 
+/**
+ * Writes the api search index to the correct location.
+ *
+ * @param project The typedoc project.
+ */
 export function writeApiSearchIndex(project: ProjectReflection): void {
   const apiIndex: APIGroup[] = [];
 
@@ -150,3 +156,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);
+}

scripts/apidoc/generate.ts

@@ -1,5 +1,9 @@
 import { resolve } from 'path';
-import { writeApiPagesIndex, writeApiSearchIndex } from './apiDocsWriter';
+import {
+  writeApiPagesIndex,
+  writeApiSearchIndex,
+  writeSourceBaseUrl,
+} from './apiDocsWriter';
 import { processModuleMethods } from './moduleMethods';
 import { loadProject } from './typedoc';
 import { pathOutputDir } from './utils';
@@ -19,4 +23,5 @@ export async function generate(): Promise<void> {
   writeApiPagesIndex(modules);
 
   writeApiSearchIndex(project);
+  writeSourceBaseUrl(project);
 }

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),

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.
  *

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 <code>bar</code> and <code>baz</code>.",
   ],
   "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.</p>
   "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",
 }
 `;