@cparra/apexdocs 3.0.0-alpha.3 → 3.0.0-alpha.4

package/dist/cli/generate.js

@@ -10,7 +10,7 @@ var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
 var Handlebars = require('handlebars');
-var defaults = require('../defaults-jLXD2y8-.js');
+var defaults = require('../defaults-DGKfeZq-.js');
 var fs = require('fs');
 var chalk = require('chalk');
 var logUpdate = require('log-update');
@@ -569,8 +569,59 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
   };
 }
 
+const generateLink = (strategy) => {
+  switch (strategy) {
+    case "relative":
+      return generateRelativeLink;
+    case "no-link":
+      return generateNoLink;
+    case "none":
+      return returnReferenceAsIs;
+  }
+};
+const generateRelativeLink = (references, from, referenceName) => {
+  function getRelativePath(fromPath, toPath) {
+    return path.relative(path.parse(path.join("/", fromPath)).dir, path.join("/", toPath));
+  }
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  if (referenceTo && from === "__base__") {
+    return {
+      __type: "link",
+      title: referenceTo.displayName,
+      url: getRelativePath("", referenceTo.referencePath)
+    };
+  }
+  const referenceFrom = references[from];
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath)
+  };
+};
+const generateNoLink = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+const returnReferenceAsIs = (references, _from, referenceName) => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  return {
+    __type: "link",
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath
+  };
+};
+
 function parsedFilesToRenderableBundle(config, parsedFiles, references) {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
   function toReferenceGuide(parsedFiles2) {
     return parsedFiles2.reduce(
       addToReferenceGuide(apply(referenceFinder, "__base__"), config, references),
@@ -604,28 +655,6 @@ function addToReferenceGuide(findLinkFromHome, config, references) {
     return acc;
   };
 }
-const linkGenerator = (references, documentationRootDir, from, referenceName) => {
-  const referenceTo = references[referenceName];
-  if (referenceTo && from === "__base__") {
-    return {
-      __type: "link",
-      title: referenceTo.displayName,
-      url: path__namespace.join(documentationRootDir, referenceTo.referencePath)
-    };
-  }
-  const referenceFrom = references[from];
-  if (!referenceFrom || !referenceTo) {
-    return referenceName;
-  }
-  const fromPath = path__namespace.parse(path__namespace.join("/", documentationRootDir, referenceFrom.referencePath)).dir;
-  const toPath = path__namespace.join("/", documentationRootDir, referenceTo.referencePath);
-  const relativePath = path__namespace.relative(fromPath, toPath);
-  return {
-    __type: "link",
-    title: referenceTo.displayName,
-    url: relativePath
-  };
-};
 function getTypeGroup$1(type, config) {
   var _a, _b;
   const groupAnnotation = (_a = type.docComment) == null ? void 0 : _a.annotations.find((annotation) => annotation.name.toLowerCase() === "group");
@@ -1716,9 +1745,25 @@ class Logger {
   static clear() {
     logUpdate.clear();
   }
+  static startSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+    }
+    this.spinnerInterval = setInterval(() => {
+      this.logSingle("Processing...", true, "green", true);
+    }, 80);
+  }
+  static stopSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = null;
+      this.clear();
+    }
+  }
 }
 Logger.currentFrame = 0;
 Logger.frames = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+Logger.spinnerInterval = null;
 
 const referenceGuideTemplate = `
 # Apex Reference Guide
@@ -2845,14 +2890,19 @@ class Apexdocs {
   static generate(config) {
     return __async$1(this, null, function* () {
       Logger.logSingle("Initializing...", false);
-      const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
-      switch (config.targetGenerator) {
-        case "markdown":
-          yield generate(fileBodies, config);
-          break;
-        case "openapi":
-          openApi(fileBodies, config);
-          break;
+      Logger.startSpinner();
+      try {
+        const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+        switch (config.targetGenerator) {
+          case "markdown":
+            yield generate(fileBodies, config);
+            break;
+          case "openapi":
+            openApi(fileBodies, config);
+            break;
+        }
+      } finally {
+        Logger.stopSpinner();
       }
     });
   }
@@ -2897,10 +2947,11 @@ const markdownOptions = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.defaults.includeMetadata
   },
-  documentationRootDir: {
+  linkingStrategy: {
     type: "string",
-    describe: "The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.",
-    default: defaults.defaults.documentationRootDir
+    describe: "The strategy to use when linking to other documentation pages.",
+    choices: ["relative", "no-link", "none"],
+    default: defaults.defaults.linkingStrategy
   }
 };
 

package/dist/defaults-DGKfeZq-.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const defaults = {
+  targetGenerator: "markdown",
+  targetDir: "./docs/",
+  scope: ["global"],
+  defaultGroupName: "Miscellaneous",
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  linkingStrategy: "relative"
+};
+
+exports.defaults = defaults;

package/dist/index.d.ts

@@ -10,6 +10,17 @@ type ConfigurableHooks = {
   transformReference: TransformReference;
 };
 
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
 type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -19,7 +30,7 @@ type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 type SourceFileMetadata = {
@@ -99,7 +110,7 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
-type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'documentationRootDir'>, 'targetGenerator'>;
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'>, 'targetGenerator'>;
 declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
 declare function skip(): Skip;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var defaults = require('./defaults-jLXD2y8-.js');
+var defaults = require('./defaults-DGKfeZq-.js');
 
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;

package/examples/markdown/docs/miscellaneous/MultiInheritanceClass.md

@@ -5,7 +5,7 @@ ns
 
 **Inheritance**
 
-[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](../miscellaneous/BaseClass.md)
+[SampleClass](../samplegroup/SampleClass.md) < [BaseClass](BaseClass.md)
 
 ## Fields
 ### `sampleEnumFromBase`

package/examples/markdown/docs/miscellaneous/SampleInterface.md

@@ -6,10 +6,12 @@ This is a sample interface
 
 **Mermaid** 
 
-graph TD 
-A[SampleInterface] -->|extends| B[ParentInterface] 
-B -->|extends| C[GrandParentInterface] 
-C -->|extends| D[GreatGrandParentInterface]
+```mermaid
+graph TD
+   A[SampleInterface] -->|extends| B[ParentInterface]
+   B -->|extends| C[GrandParentInterface]
+   C -->|extends| D[GreatGrandParentInterface]
+```
 
 **Author** John Doe
 
@@ -17,17 +19,19 @@ C -->|extends| D[GreatGrandParentInterface]
 
 **See** [SampleEnum](../sample-enums/SampleEnum.md)
 
-**See** [ReferencedEnum](../miscellaneous/ReferencedEnum.md)
+**See** [ReferencedEnum](ReferencedEnum.md)
 
 ## Namespace
 ns
 
 ## Example
-SampleInterface sampleInterface = new SampleInterface(); 
+```apex
+SampleInterface sampleInterface = new SampleInterface();
 sampleInterface.sampleMethod();
+```
 
 **Extends**
-[ParentInterface](../miscellaneous/ParentInterface.md)
+[ParentInterface](ParentInterface.md)
 
 ## Methods
 ### `sampleMethod()`
@@ -62,7 +66,7 @@ public String sampleMethod()
 Some return value
 
 #### Throws
-[SampleException](../miscellaneous/SampleException.md): This is a sample exception
+[SampleException](SampleException.md): This is a sample exception
 
 AnotherSampleException: This is another sample exception
 

package/examples/markdown/docs/miscellaneous/Url.md

@@ -115,7 +115,7 @@ global Url(Url context, String spec)
 #### Parameters
 | Name | Type | Description |
 |------|------|-------------|
-| context | [Url](../miscellaneous/Url.md) | The context in which to parse the specification. |
+| context | [Url](Url.md) | The context in which to parse the specification. |
 | spec | String | The string to parse as a URL. |
 
 ---
@@ -186,7 +186,7 @@ global static Url getCurrentRequestUrl()
 ```
 
 #### Return Type
-**[Url](../miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 The URL of the entire request.
 
@@ -294,7 +294,7 @@ global static Url getOrgDomainUrl()
 ```
 
 #### Return Type
-**[Url](../miscellaneous/Url.md)**
+**[Url](Url.md)**
 
 getOrgDomainUrl() always returns the login URL for your org, regardless of context. Use that URL when making API calls to your org.
 

package/examples/markdown/force-app/classes/SampleInterface.cls

@@ -5,13 +5,17 @@
  * @see SampleEnum
  * @see ReferencedEnum
  * @mermaid
+ * ```mermaid
  * graph TD
  *    A[SampleInterface] -->|extends| B[ParentInterface]
  *    B -->|extends| C[GrandParentInterface]
  *    C -->|extends| D[GreatGrandParentInterface]
+ * ```
  * @example
+ * ```apex
  * SampleInterface sampleInterface = new SampleInterface();
  * sampleInterface.sampleMethod();
+ * ```
  */
 @NamespaceAccessible
 public interface SampleInterface extends ParentInterface {

package/examples/vitepress/docs/miscellaneous/BaseClass.md

@@ -17,4 +17,4 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.0.0-alpha.3",
+  "version": "3.0.0-alpha.4",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",

package/src/application/Apexdocs.ts

@@ -15,16 +15,21 @@ export class Apexdocs {
    */
   static async generate(config: UserDefinedConfig): Promise<void> {
     Logger.logSingle('Initializing...', false);
+    Logger.startSpinner();
 
-    const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
+    try {
+      const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem(), config.sourceDir, config.includeMetadata);
 
-    switch (config.targetGenerator) {
-      case 'markdown':
-        await markdown(fileBodies, config);
-        break;
-      case 'openapi':
-        openApi(fileBodies, config);
-        break;
+      switch (config.targetGenerator) {
+        case 'markdown':
+          await markdown(fileBodies, config);
+          break;
+        case 'openapi':
+          openApi(fileBodies, config);
+          break;
+      }
+    } finally {
+      Logger.stopSpinner();
     }
   }
 }

package/src/cli/commands/markdown.ts

@@ -44,10 +44,10 @@ export const markdownOptions: { [key: string]: Options } = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.includeMetadata,
   },
-  documentationRootDir: {
+  linkingStrategy: {
     type: 'string',
-    describe:
-      'The root directory of the documentation. This is used to create the correct relative paths when generating links between documents.',
-    default: defaults.documentationRootDir,
+    describe: 'The strategy to use when linking to other documentation pages.',
+    choices: ['relative', 'no-link', 'none'],
+    default: defaults.linkingStrategy,
   },
 };

package/src/core/markdown/__test__/generating-class-docs.spec.ts

@@ -268,9 +268,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [ClassRef](/miscellaneous/ClassRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [ClassRef](ClassRef.md) reference'),
         );
       });
 
@@ -304,7 +302,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](/miscellaneous/ClassRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](ClassRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-enum-docs.spec.ts

@@ -211,7 +211,7 @@ describe('Generates enum documentation', () => {
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('Description'));
       assertEither(result, (data) =>
-        expect(data).firstDocContains('This is a description with a [EnumRef](/miscellaneous/EnumRef.md) reference'),
+        expect(data).firstDocContains('This is a description with a [EnumRef](EnumRef.md) reference'),
       );
     });
 
@@ -245,7 +245,7 @@ describe('Generates enum documentation', () => {
       const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
       expect(result).documentationBundleHasLength(2);
       assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](/miscellaneous/EnumRef.md)'));
+      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](EnumRef.md)'));
     });
 
     it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-interface-docs.spec.ts

@@ -189,9 +189,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with a [InterfaceRef](/miscellaneous/InterfaceRef.md) reference',
-          ),
+          expect(data).firstDocContains('This is a description with a [InterfaceRef](InterfaceRef.md) reference'),
         );
       });
 
@@ -225,7 +223,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](/miscellaneous/InterfaceRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](InterfaceRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {

package/src/core/markdown/__test__/generating-reference-guide.spec.ts

@@ -25,10 +25,10 @@ describe('Generates a Reference Guide', () => {
     expect(result).documentationBundleHasLength(2);
 
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](/miscellaneous/MyEnum.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](miscellaneous/MyEnum.md)'),
     );
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](/miscellaneous/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](miscellaneous/MyClass.md)'),
     );
   });
 
@@ -174,7 +174,7 @@ describe('Generates a Reference Guide', () => {
     const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
     expect(result).documentationBundleHasLength(2);
     assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](/group2/MyClass.md)'),
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](group2/MyClass.md)'),
     );
   });
 });

package/src/core/markdown/__test__/test-helpers.ts

@@ -17,7 +17,7 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     defaultGroupName: 'Miscellaneous',
     sortMembersAlphabetically: true,
     referenceGuideTemplate: referenceGuideTemplate,
+    linkingStrategy: 'relative',
     ...config,
-    documentationRootDir: '',
   });
 }

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -15,7 +15,7 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
   sortMembersAlphabetically: false,
-  documentationRootDir: '',
+  linkingStrategy: 'relative',
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

package/src/core/markdown/adapters/__tests__/link-generator.spec.ts

@@ -0,0 +1,130 @@
+import { generateLink } from '../generate-link';
+
+describe('Generates links', () => {
+  describe('relative', () => {
+    it('generates relative links from the base when found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns a relative path when linking from a file', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+        from: {
+          referencePath: 'b/fromPath',
+          displayName: 'fromName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: '../a/referencePath',
+      });
+    });
+
+    it('returns the display name when the from reference is not found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'a/referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = 'from';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('relative')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('no-link', () => {
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+
+    it('returns the display name of the reference when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('no-link')(references, from, referenceName);
+
+      expect(result).toEqual('displayName');
+    });
+  });
+
+  describe('none', () => {
+    it('returns the path as is when the reference is found', () => {
+      const references = {
+        referenceName: {
+          referencePath: 'referencePath',
+          displayName: 'displayName',
+        },
+      };
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual({
+        __type: 'link',
+        title: 'displayName',
+        url: 'referencePath',
+      });
+    });
+
+    it('returns the name of the reference when the reference is not found', () => {
+      const references = {};
+      const from = '__base__';
+      const referenceName = 'referenceName';
+
+      const result = generateLink('none')(references, from, referenceName);
+
+      expect(result).toEqual('referenceName');
+    });
+  });
+});

package/src/core/markdown/adapters/generate-link.ts

@@ -0,0 +1,82 @@
+import { StringOrLink } from './types';
+import path from 'path';
+import { LinkingStrategy } from '../../shared/types';
+
+export type LinkingStrategyFn = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string,
+  referenceName: string,
+) => StringOrLink;
+
+export const generateLink = (strategy: LinkingStrategy): LinkingStrategyFn => {
+  switch (strategy) {
+    case 'relative':
+      return generateRelativeLink;
+    case 'no-link':
+      return generateNoLink;
+    case 'none':
+      return returnReferenceAsIs;
+  }
+};
+
+const generateRelativeLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  from: string, // The name of the file for which the reference is being generated
+  referenceName: string,
+): StringOrLink => {
+  function getRelativePath(fromPath: string, toPath: string) {
+    return path.relative(path.parse(path.join('/', fromPath)).dir, path.join('/', toPath));
+  }
+
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
+  // path.
+  if (referenceTo && from === '__base__') {
+    return {
+      __type: 'link',
+      title: referenceTo.displayName,
+      url: getRelativePath('', referenceTo.referencePath),
+    };
+  }
+
+  const referenceFrom = references[from];
+
+  if (!referenceFrom) {
+    return referenceTo.displayName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: getRelativePath(referenceFrom.referencePath, referenceTo.referencePath),
+  };
+};
+
+const generateNoLink = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  return referenceTo ? referenceTo.displayName : referenceName;
+};
+
+const returnReferenceAsIs = (
+  references: Record<string, { referencePath: string; displayName: string } | undefined>,
+  _from: string,
+  referenceName: string,
+): StringOrLink => {
+  const referenceTo = references[referenceName];
+  if (!referenceTo) {
+    return referenceName;
+  }
+
+  return {
+    __type: 'link',
+    title: referenceTo.displayName,
+    url: referenceTo.referencePath,
+  };
+};

package/src/core/markdown/adapters/renderable-bundle.ts

@@ -1,18 +1,18 @@
 import { DocPageReference, ParsedFile } from '../../shared/types';
-import { Link, ReferenceGuideReference, Renderable, RenderableBundle, StringOrLink } from './types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle } from './types';
 import { typeToRenderable } from './apex-types';
 import { adaptDescribable } from './documentables';
 import { MarkdownGeneratorConfig } from '../generate-docs';
 import { apply } from '#utils/fp';
 import { Type } from '@cparra/apex-reflection';
-import * as path from 'path';
+import { generateLink } from './generate-link';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
   references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
 
   function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
     return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
@@ -55,43 +55,6 @@ function addToReferenceGuide(
   };
 }
 
-const linkGenerator = (
-  references: Record<string, DocPageReference>,
-  documentationRootDir: string,
-  from: string, // The name of the file for which the reference is being generated
-  referenceName: string,
-): StringOrLink => {
-  const referenceTo: DocPageReference | undefined = references[referenceName];
-  // When linking from the base path (e.g. the reference guide/index page), the reference path is the same as the output
-  // path.
-  if (referenceTo && from === '__base__') {
-    return {
-      __type: 'link',
-      title: referenceTo.displayName,
-      url: path.join(documentationRootDir, referenceTo.referencePath),
-    };
-  }
-
-  const referenceFrom: DocPageReference | undefined = references[from];
-
-  if (!referenceFrom || !referenceTo) {
-    return referenceName;
-  }
-
-  // Gets the directory of the file that is being linked from.
-  // This is used to calculate the relative path to the file
-  // being linked to.
-  const fromPath = path.parse(path.join('/', documentationRootDir, referenceFrom.referencePath)).dir;
-  const toPath = path.join('/', documentationRootDir, referenceTo.referencePath);
-  const relativePath = path.relative(fromPath, toPath);
-
-  return {
-    __type: 'link',
-    title: referenceTo.displayName,
-    url: relativePath,
-  };
-};
-
 function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
   const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
   return groupAnnotation?.body ?? config.defaultGroupName;

package/src/core/markdown/generate-docs.ts

@@ -42,7 +42,7 @@ export type MarkdownGeneratorConfig = Pick<
   | 'transformDocs'
   | 'transformDocPage'
   | 'transformReference'
-  | 'documentationRootDir'
+  | 'linkingStrategy'
 > & {
   referenceGuideTemplate: string;
   sortMembersAlphabetically: boolean;

package/src/core/shared/types.d.ts

@@ -12,6 +12,17 @@ export type ConfigurableHooks = {
   transformReference: TransformReference;
 };
 
+type LinkingStrategy =
+  // Links will be generated using relative paths.
+  | 'relative'
+  // No links will be generated.
+  // If the reference is found, the display name will be used.
+  // Otherwise, the name
+  // of the reference itself will be used.
+  | 'no-link'
+  // No logic will be applied, the reference path will be used as is.
+  | 'none';
+
 export type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   sourceDir: string;
@@ -21,7 +32,7 @@ export type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
-  documentationRootDir: string;
+  linkingStrategy: LinkingStrategy;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {

package/src/defaults.ts

@@ -5,5 +5,5 @@ export const defaults = {
   defaultGroupName: 'Miscellaneous',
   includeMetadata: false,
   sortMembersAlphabetically: false,
-  documentationRootDir: '',
+  linkingStrategy: 'relative' as const,
 };

package/src/index.ts

@@ -12,12 +12,7 @@ import { defaults } from './defaults';
 type ConfigurableMarkdownConfig = Omit<
   SetOptional<
     UserDefinedMarkdownConfig,
-    | 'targetDir'
-    | 'scope'
-    | 'defaultGroupName'
-    | 'includeMetadata'
-    | 'sortMembersAlphabetically'
-    | 'documentationRootDir'
+    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'
   >,
   'targetGenerator'
 >;

package/src/util/logger.ts

@@ -8,6 +8,7 @@ export class Logger {
   static currentFrame = 0;
 
   static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  static spinnerInterval: NodeJS.Timeout | null = null;
 
   /**
    * Logs a message with optional arguments.
@@ -54,4 +55,21 @@ export class Logger {
   public static clear() {
     logUpdate.clear();
   }
+
+  public static startSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+    }
+    this.spinnerInterval = setInterval(() => {
+      this.logSingle('Processing...', true, 'green', true);
+    }, 80);
+  }
+
+  public static stopSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+      this.spinnerInterval = null;
+      this.clear();
+    }
+  }
 }