docs: update rendering to use generated repo link (angular#61143)

PR Close angular#61143

Author: mmalerba

adev/shared-docs/pipeline/api-gen/extraction/test/BUILD.bazel

@@ -16,6 +16,7 @@ extract_api_to_json(
     module_name = "@angular/core",
     output_name = "api.json",
     private_modules = [""],
+    repo = "angular/angular",
 )
 
 extract_api_to_json(
@@ -34,6 +35,7 @@ extract_api_to_json(
     module_name = "@angular/core",
     output_name = "extra_api.json",
     private_modules = [""],
+    repo = "angular/angular",
 )
 
 filegroup(

adev/shared-docs/pipeline/api-gen/manifest/test/BUILD.bazel

@@ -1,5 +1,5 @@
-load("//adev/shared-docs/pipeline/api-gen/manifest:generate_api_manifest.bzl", "generate_api_manifest")
 load("//adev/shared-docs/pipeline/api-gen/extraction:extract_api_to_json.bzl", "extract_api_to_json")
+load("//adev/shared-docs/pipeline/api-gen/manifest:generate_api_manifest.bzl", "generate_api_manifest")
 load("//tools:defaults.bzl", "jasmine_node_test", "ts_library")
 
 generate_api_manifest(
@@ -17,6 +17,7 @@ extract_api_to_json(
     module_name = "@angular/router",
     output_name = "api.json",
     private_modules = [""],
+    repo = "angular/angular",
 )
 
 ts_library(

adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.ts

@@ -33,6 +33,7 @@ export interface JsDocTagRenderable extends JsDocTagEntry {
 
 /** A documentation entry augmented with transformed content for rendering. */
 export interface DocEntryRenderable extends DocEntry {
+  repo: string;
   moduleName: string;
   htmlDescription: string;
   shortHtmlDescription: string;

adev/shared-docs/pipeline/api-gen/rendering/entities/traits.ts

@@ -71,6 +71,11 @@ export interface HasModuleName {
   moduleName: string;
 }
 
+/** A doc entry that has an associated github repo. */
+export interface HasRepo {
+  repo: string;
+}
+
 /** A doc entry that has ToC transformed for rendering. */
 export interface HasRenderableToc {
   beforeCodeGroups: string;

adev/shared-docs/pipeline/api-gen/rendering/index.ts

@@ -19,6 +19,7 @@ import {setCurrentSymbol, setSymbols} from './symbol-context';
 
 /** The JSON data file format for extracted API reference info. */
 interface EntryCollection {
+  repo: string;
   moduleName: string;
   moduleLabel?: string;
   normalizedModuleName: string;
@@ -44,13 +45,15 @@ function parseEntryData(srcs: string[]): EntryCollection[] {
       const command = fileContentJson as CliCommand;
       return [
         {
+          repo: 'anglar/cli',
           moduleName: 'unknown',
           normalizedModuleName: 'unknown',
           entries: [fileContentJson as DocEntry],
           symbols: new Map(),
         },
         ...command.subcommands!.map((subCommand) => {
           return {
+            repo: 'angular/cli',
             moduleName: 'unknown',
             normalizedModuleName: 'unknown',
             entries: [{...subCommand, parentCommand: command} as any],
@@ -61,6 +64,7 @@ function parseEntryData(srcs: string[]): EntryCollection[] {
     }
 
     return {
+      repo: 'unknown',
       moduleName: 'unknown',
       normalizedModuleName: 'unknown',
       entries: [fileContentJson as DocEntry], // TODO: fix the typing cli entries aren't DocEntry
@@ -122,7 +126,7 @@ async function main() {
 
     const renderableEntries = extractedEntries.map((entry) => {
       setCurrentSymbol(entry.name);
-      return getRenderable(entry, collection.moduleName);
+      return getRenderable(entry, collection.moduleName, collection.repo);
     });
 
     const htmlOutputs = renderableEntries.map(renderEntry);

adev/shared-docs/pipeline/api-gen/rendering/processing.ts

@@ -8,6 +8,7 @@
 
 import {DocEntry} from './entities';
 
+import {CliCommand} from './cli-entities';
 import {
   isClassEntry,
   isCliEntry,
@@ -21,9 +22,9 @@ import {
 } from './entities/categorization';
 import {CliCommandRenderable, DocEntryRenderable} from './entities/renderables';
 import {getClassRenderable} from './transforms/class-transforms';
-import {getDecoratorRenderable} from './transforms/decorator-transforms';
 import {getCliRenderable} from './transforms/cli-transforms';
 import {getConstantRenderable} from './transforms/constant-transforms';
+import {getDecoratorRenderable} from './transforms/decorator-transforms';
 import {getEnumRenderable} from './transforms/enum-transforms';
 import {getFunctionRenderable} from './transforms/function-transforms';
 import {getInitializerApiFunctionRenderable} from './transforms/initializer-api-functions-transform';
@@ -36,47 +37,48 @@ import {
   setEntryFlags,
 } from './transforms/jsdoc-transforms';
 import {addModuleName} from './transforms/module-name';
+import {addRepo} from './transforms/repo';
 import {getTypeAliasRenderable} from './transforms/type-alias-transforms';
-import {CliCommand} from './cli-entities';
 
 export function getRenderable(
   entry: DocEntry | CliCommand,
   moduleName: string,
+  repo: string,
 ): DocEntryRenderable | CliCommandRenderable {
   if (isCliEntry(entry)) {
     return getCliRenderable(entry);
   }
 
   if (isClassEntry(entry)) {
-    return getClassRenderable(entry, moduleName);
+    return getClassRenderable(entry, moduleName, repo);
   }
   if (isDecoratorEntry(entry)) {
-    return getDecoratorRenderable(entry, moduleName);
+    return getDecoratorRenderable(entry, moduleName, repo);
   }
   if (isConstantEntry(entry)) {
-    return getConstantRenderable(entry, moduleName);
+    return getConstantRenderable(entry, moduleName, repo);
   }
   if (isEnumEntry(entry)) {
-    return getEnumRenderable(entry, moduleName);
+    return getEnumRenderable(entry, moduleName, repo);
   }
   if (isInterfaceEntry(entry)) {
-    return getInterfaceRenderable(entry, moduleName);
+    return getInterfaceRenderable(entry, moduleName, repo);
   }
   if (isFunctionEntry(entry)) {
-    return getFunctionRenderable(entry, moduleName);
+    return getFunctionRenderable(entry, moduleName, repo);
   }
   if (isTypeAliasEntry(entry)) {
-    return getTypeAliasRenderable(entry, moduleName);
+    return getTypeAliasRenderable(entry, moduleName, repo);
   }
   if (isInitializerApiFunctionEntry(entry)) {
-    return getInitializerApiFunctionRenderable(entry, moduleName);
+    return getInitializerApiFunctionRenderable(entry, moduleName, repo);
   }
 
   // Fallback to an uncategorized renderable.
   return setEntryFlags(
     addHtmlAdditionalLinks(
       addHtmlDescription(
-        addHtmlUsageNotes(addHtmlJsDocTagComments(addModuleName(entry, moduleName))),
+        addHtmlUsageNotes(addHtmlJsDocTagComments(addRepo(addModuleName(entry, moduleName), repo))),
       ),
     ),
   );

adev/shared-docs/pipeline/api-gen/rendering/templates/class-member.tsx

@@ -20,19 +20,19 @@ import {
   REFERENCE_MEMBER_CARD_HEADER,
   REFERENCE_MEMBER_CARD_ITEM,
 } from '../styling/css-classes';
+import {getFunctionMetadataRenderable} from '../transforms/function-transforms';
 import {ClassMethodInfo} from './class-method-info';
+import {CodeSymbol} from './code-symbols';
 import {DeprecatedLabel} from './deprecated-label';
 import {RawHtml} from './raw-html';
-import {getFunctionMetadataRenderable} from '../transforms/function-transforms';
-import {CodeSymbol} from './code-symbols';
 
 export function ClassMember(props: {member: MemberEntryRenderable}) {
   const member = props.member;
 
   const renderMethod = (method: MethodEntryRenderable) => {
     const signature = method.signatures.length ? method.signatures : [method.implementation];
     return signature.map((sig) => {
-      const renderableMember = getFunctionMetadataRenderable(sig);
+      const renderableMember = getFunctionMetadataRenderable(sig, method.moduleName, method.repo);
       return <ClassMethodInfo entry={renderableMember} options={{showUsageNotes: true}} />;
     });
   };

adev/shared-docs/pipeline/api-gen/rendering/templates/class-reference.tsx

@@ -7,25 +7,25 @@
  */
 
 import {Fragment, h} from 'preact';
+import {PipeEntry} from '../entities';
 import {
   ClassEntryRenderable,
   DecoratorEntryRenderable,
   PipeEntryRenderable,
 } from '../entities/renderables';
-import {ClassMemberList} from './class-member-list';
-import {HeaderApi} from './header-api';
+import {codeToHtml} from '../shiki/shiki';
 import {
   API_REFERENCE_CONTAINER,
   REFERENCE_MEMBERS,
   SECTION_CONTAINER,
 } from '../styling/css-classes';
-import {SectionDescription} from './section-description';
-import {SectionUsageNotes} from './section-usage-notes';
+import {ClassMemberList} from './class-member-list';
+import {HeaderApi} from './header-api';
+import {RawHtml} from './raw-html';
 import {SectionApi} from './section-api';
+import {SectionDescription} from './section-description';
 import {SectionHeading} from './section-heading';
-import {PipeEntry} from '../entities';
-import {codeToHtml} from '../shiki/shiki';
-import {RawHtml} from './raw-html';
+import {SectionUsageNotes} from './section-usage-notes';
 
 /** Component to render a class API reference document. */
 export function ClassReference(

adev/shared-docs/pipeline/api-gen/rendering/templates/function-reference.tsx

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {h, Fragment} from 'preact';
+import {Fragment, h} from 'preact';
 import {
   FunctionEntryRenderable,
   FunctionSignatureMetadataRenderable,
@@ -18,15 +18,15 @@ import {
   REFERENCE_MEMBER_CARD_BODY,
   REFERENCE_MEMBER_CARD_HEADER,
 } from '../styling/css-classes';
+import {printInitializerFunctionSignatureLine} from '../transforms/code-transforms';
+import {getFunctionMetadataRenderable} from '../transforms/function-transforms';
 import {ClassMethodInfo} from './class-method-info';
+import {CodeSymbol} from './code-symbols';
 import {HeaderApi} from './header-api';
+import {HighlightTypeScript} from './highlight-ts';
 import {SectionApi} from './section-api';
 import {SectionDescription} from './section-description';
 import {SectionUsageNotes} from './section-usage-notes';
-import {HighlightTypeScript} from './highlight-ts';
-import {printInitializerFunctionSignatureLine} from '../transforms/code-transforms';
-import {getFunctionMetadataRenderable} from '../transforms/function-transforms';
-import {CodeSymbol} from './code-symbols';
 
 export const signatureCard = (
   name: string,
@@ -75,7 +75,7 @@ export function FunctionReference(entry: FunctionEntryRenderable) {
         {entry.signatures.map((s, i) =>
           signatureCard(
             s.name,
-            getFunctionMetadataRenderable(s, entry.moduleName),
+            getFunctionMetadataRenderable(s, entry.moduleName, entry.repo),
             {
               id: `${s.name}_${i}`,
             },

adev/shared-docs/pipeline/api-gen/rendering/templates/header-api.tsx

@@ -18,7 +18,10 @@ import {
 import {DocsPillRow} from './docs-pill-row';
 
 /** Component to render a header of the API page. */
-export function HeaderApi(props: {entry: DocEntryRenderable | PipeEntryRenderable; showFullDescription?: boolean}) {
+export function HeaderApi(props: {
+  entry: DocEntryRenderable | PipeEntryRenderable;
+  showFullDescription?: boolean;
+}) {
   const entry = props.entry;
 
   // TODO: This link point to the main branch.
@@ -52,9 +55,7 @@ export function HeaderApi(props: {entry: DocEntryRenderable | PipeEntryRenderabl
           )}
 
           {entry.entryType === EntryType.Pipe && !(entry as PipeEntry).isPure && (
-            <div className={`${HEADER_ENTRY_LABEL} type-impure-pipe full`}>
-              Impure
-            </div>
+            <div className={`${HEADER_ENTRY_LABEL} type-impure-pipe full`}>Impure</div>
           )}
         </div>
         {sourceUrl && (
@@ -107,6 +108,7 @@ function sourceUrlForEntry(entry: DocEntryRenderable): string | null {
     // We don't know the source path in external repos link the CLI
     return null;
   } else {
-    return `https://github.com/angular/angular/blob/main${entry.source.filePath}#L${entry.source.startLine}-L${entry.source.endLine}`;
+    const filePath = entry.source.filePath.replace(/^\//, '');
+    return `https://github.com/${entry.repo}/blob/main/${filePath}#L${entry.source.startLine}-L${entry.source.endLine}`;
   }
 }