feat(dgeni): automatically generate API doc links for code span in ma…

…rkdown (#2964)

libs/analytics/README.md

@@ -9,7 +9,7 @@ The Daffodil Analytics Module is a lightweight Angular package that helps integr
 
 ## Usage
 
-In this example, `MyAnalyticsService` implements the [`DaffAnalyticsTrackerClass`](/libs/analytics/DaffAnalyticsTrackerClass.ts) interface, providing a track method. Inside the track method, you can define your custom logic for tracking analytics events based on the provided action. The service returns an observable, indicating the success of the tracking operation. Replace the logic inside the track method with your actual analytics tracking implementation.
+In this example, `MyAnalyticsService` implements the `DaffAnalyticsTrackerClass` interface, providing a track method. Inside the track method, you can define your custom logic for tracking analytics events based on the provided action. The service returns an observable, indicating the success of the tracking operation. Replace the logic inside the track method with your actual analytics tracking implementation.
 
 ### Define a tracking service
 

libs/cart/guides/state.md

@@ -6,21 +6,21 @@ The facade is an abstraction that provides all the functionality needed for stan
 
 ## Setting up `AppModule`
 
-To get started, import the `DaffCartModule` in `AppModule`. Next, import `StoreModule.forRoot({})`, which will be relevant later on when using the redux and state management features of the cart module.
+To get started, import the `DaffCartStateModule` in `AppModule`. Next, import `StoreModule.forRoot({})`, which will be relevant later on when using the redux and state management features of the cart module.
 
 ```typescript
 @ngModule({
   imports:[
     StoreModule.forRoot({}),
-    DaffCartModule
+    DaffCartStateModule
   ]
 })
 export class AppModule {}
 ```
 
 ## Using the Facade
 
-The `DaffCartModule` provides a `DaffCartFacade` that wraps the complexities of the state library into one place. This facade will handle updating the user's cart and can also be used to build UI with behaviors common to a cart.
+The `DaffCartStateModule` provides a `DaffCartFacade` that wraps the complexities of the state library into one place. This facade will handle updating the user's cart and can also be used to build UI with behaviors common to a cart.
 
 To inject the facade inside a component, include an instance of `DaffCartFacade` in the component's constructor.
 
@@ -137,7 +137,7 @@ This tutorial will walk you through Daffodil's Cart Resolution process which is
 
 At the moment, the following scenarios are handled by the `DaffResolvedCartGuard`.
 
-> For customer cart support, use the [`@daffodil/cart-customer`](/libs/cart-customer/README.md) package.
+> For customer cart support, use the [@daffodil/cart-customer](/libs/cart-customer/README.md) package.
 
 - Generating a new cart when a user visits the application for the very first time.
 - Retrieving a previously existing cart for a user upon page reload.

libs/payment/README.md

@@ -2,7 +2,7 @@
 
 `@daffodil/payment` contains the main features required to support payment in an Angular app. `@daffodil/payment` doesn't inherently support any particular payment methods but instead provides base models and extension points that are utilized by other libraries.
 
-See [`@daffodil/authorizenet`](../authorizenet/README.md) for an example of such a library.
+See [@daffodil/authorizenet](../authorizenet/README.md) for an example of such a library.
 
 ## Installation
 

libs/search/README.md

@@ -2,7 +2,7 @@
 
 `@daffodil/search` contains the main features required to build search in an Angular app. `@daffodil/search` doesn't inherently support searching for any particular entities but instead provides base models and extension points that are utilized by other libraries.
 
-See [`@daffodil/search-product`](../search-product/README.md) for an example of such a library.
+See [@daffodil/search-product](../search-product/README.md) for an example of such a library.
 
 ## Installation
 

tools/dgeni/build.ts

@@ -10,9 +10,10 @@ import {
 } from './src/transforms/daffodil-guides-package';
 
 rimraf('../../dist/docs/*', { glob: true }).then(() => {
-  new Dgeni([packageDocsPackage]).generate().catch(() => process.exit(1));
-  new Dgeni([guideDocsPackage]).generate().catch(() => process.exit(1));
-  new Dgeni([explanationDocsPackage]).generate().catch(() => process.exit(1));
-  new Dgeni([apiDocs]).generate().catch(() => process.exit(1));
-  new Dgeni([designExamplePackage]).generate().catch(() => process.exit(1));
+  new Dgeni([apiDocs]).generate().then(() => {
+    new Dgeni([packageDocsPackage]).generate().catch(() => process.exit(1));
+    new Dgeni([guideDocsPackage]).generate().catch(() => process.exit(1));
+    new Dgeni([explanationDocsPackage]).generate().catch(() => process.exit(1));
+    new Dgeni([designExamplePackage]).generate().catch(() => process.exit(1));
+  }).catch(() => process.exit(1));
 });

tools/dgeni/src/processors/collect-linkable-symbols.ts

@@ -0,0 +1,34 @@
+import {
+  Processor,
+  Document,
+} from 'dgeni';
+
+export const COLLECT_LINKABLE_SYMBOLS_PROCESSOR_NAME = 'collectLinkableSymbols';
+
+/**
+ * Stores a list of symbols and their paths.
+ */
+export class CollectLinkableSymbolsProcessor implements Processor {
+  private static readonly _symbols = new Map<string, string>();
+
+  public static get symbols(): ReadonlyMap<string, string> {
+    return this._symbols;
+  }
+
+  name = COLLECT_LINKABLE_SYMBOLS_PROCESSOR_NAME;
+  $runAfter = ['paths-computed'];
+  $runBefore = ['markdown'];
+
+  constructor(private log, private createDocMessage) {}
+
+  $process(docs: Document[]): Document[] {
+	  docs.forEach((doc) => {
+      if (CollectLinkableSymbolsProcessor._symbols.get(doc.name)) {
+        this.log.warn(this.createDocMessage(`Linkable symbol collision for name ${doc.name}. Existing path: ${CollectLinkableSymbolsProcessor._symbols.get(doc.name)}, new path: ${doc.path}`));
+      }
+      CollectLinkableSymbolsProcessor._symbols.set(doc.name, doc.path);
+    });
+
+	  return docs;
+  }
+}

tools/dgeni/src/processors/markdown.ts

@@ -17,6 +17,8 @@ import {
   DaffDocKind,
 } from '@daffodil/docs-utils';
 
+import { CollectLinkableSymbolsProcessor } from './collect-linkable-symbols';
+
 hljs.registerLanguage('typescript', typescript);
 hljs.registerLanguage('ts', typescript);
 hljs.registerLanguage('xml', xml);
@@ -66,13 +68,22 @@ marked.use(
 
 marked.use({
   walkTokens: (token) => {
-    if (token.type === 'link') {
-      token.href = getLinkUrl(token.href);
+    switch (token.type) {
+      case 'link':
+        token.href = getLinkUrl(token.href);
+        break;
+
+      default:
+        break;
     }
   },
   renderer: {
     heading: (text: string, level: number, raw: string) =>
       `<h${level} id="${slugify(raw)}">${text}</h${level}>`,
+    codespan: (text: string): string | false => {
+      const path = CollectLinkableSymbolsProcessor.symbols.get(text);
+      return path ? `<a href="${path}"><code>${text}</code></a>` : false;
+    },
   },
 });
 

tools/dgeni/src/transforms/daffodil-api-package/index.ts

@@ -10,6 +10,10 @@ import { DAFF_DGENI_EXCLUDED_PACKAGES_REGEX } from '../../constants/excluded-pac
 import { AddInheritedDocsContentProcessor } from '../../processors/addInheritedDocsContent';
 import { AddLinkTagToDaffodilReferencesProcessor } from '../../processors/addLinkTagToDaffodilReferences';
 import { CleanSelectorsProcessor } from '../../processors/cleanSelectors';
+import {
+  COLLECT_LINKABLE_SYMBOLS_PROCESSOR_NAME,
+  CollectLinkableSymbolsProcessor,
+} from '../../processors/collect-linkable-symbols';
 import { CrossEnvSafeNameProcessor } from '../../processors/cross-env-safe-name';
 import { FilterContainedDocsProcessor } from '../../processors/filterDocs';
 import { FilterOutPrivatePropertiesProcessor } from '../../processors/filterOutPrivateProperties';
@@ -26,7 +30,9 @@ import { daffodilBasePackage } from '../daffodil-base-package';
 const linksPackage = require('dgeni-packages/links');
 const typescriptPackage = require('dgeni-packages/typescript');
 
-export const apiDocs = new Package('daffodil-api', [
+const API_PACKAGE_NAME = 'daffodil-api';
+
+export const apiDocs = new Package(API_PACKAGE_NAME, [
   daffodilBasePackage,
   typescriptPackage,
   linksPackage,
@@ -42,6 +48,7 @@ export const apiDocs = new Package('daffodil-api', [
   .processor(new GenerateApiListProcessor())
   .processor(new PackagesProcessor())
   .processor(new MarkdownCodeProcessor())
+  .processor(COLLECT_LINKABLE_SYMBOLS_PROCESSOR_NAME, (log, createDocMessage) => new CollectLinkableSymbolsProcessor(log, createDocMessage))
   .factory('API_DOC_TYPES_TO_RENDER', (EXPORT_DOC_TYPES) => EXPORT_DOC_TYPES.concat(['component', 'directive', 'pipe', 'package']))
   //Configure our package
   .config((readFilesProcessor, readTypeScriptModules, tsParser) => {