@cparra/apexdocs 2.25.0-alpha.6 → 2.25.0-alpha.9

package/src/application/file-writer.ts

@@ -5,21 +5,17 @@ import { PageData } from '../core/shared/types';
 export class FileWriter {
   static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
     files.forEach((file) => {
-      const resolvedFile = this.getTargetLocation(file, outputDir);
-      if (!fs.existsSync(resolvedFile.directory)) {
-        fs.mkdirSync(resolvedFile.directory, { recursive: true });
-      }
-
-      const filePath = path.join(resolvedFile.directory, `${resolvedFile.fileName}.${resolvedFile.fileExtension}`);
-      fs.writeFileSync(filePath, resolvedFile.content, 'utf8');
-      onWriteCallback(resolvedFile);
+      const { filePath, content } = this.getTargetLocation(file, outputDir);
+      fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      fs.writeFileSync(filePath, content, 'utf8');
+      onWriteCallback(file);
     });
   }
 
   private static getTargetLocation(file: PageData, outputDir: string): PageData {
     return {
       ...file,
-      directory: path.join(outputDir, file.directory),
+      filePath: path.join(outputDir, file.filePath),
     };
   }
 }

package/src/application/generators/markdown.ts

@@ -2,13 +2,18 @@ import { generateDocs } from '../../core/markdown/generate-docs';
 import { FileWriter } from '../file-writer';
 import { Logger } from '#utils/logger';
 import { pipe } from 'fp-ts/function';
-import { PageData, PostHookDocumentationBundle, SourceFile, UserDefinedMarkdownConfig } from '../../core/shared/types';
+import {
+  PageData,
+  PostHookDocumentationBundle,
+  UnparsedSourceFile,
+  UserDefinedMarkdownConfig,
+} from '../../core/shared/types';
 import { ReflectionError } from '../../core/markdown/reflection/error-handling';
 import { referenceGuideTemplate } from '../../core/markdown/templates/reference-guide';
 import * as TE from 'fp-ts/TaskEither';
 import { isSkip } from '../../core/shared/utils';
 
-export default function generate(bundles: SourceFile[], config: UserDefinedMarkdownConfig) {
+export default function generate(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
   return pipe(
     generateDocumentationBundle(bundles, config),
     TE.map((files) => writeFilesToSystem(files, config.targetDir)),
@@ -29,7 +34,7 @@ export default function generate(bundles: SourceFile[], config: UserDefinedMarkd
   )();
 }
 
-function generateDocumentationBundle(bundles: SourceFile[], config: UserDefinedMarkdownConfig) {
+function generateDocumentationBundle(bundles: UnparsedSourceFile[], config: UserDefinedMarkdownConfig) {
   return generateDocs(bundles, {
     ...config,
     referenceGuideTemplate: referenceGuideTemplate,
@@ -43,7 +48,7 @@ function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: strin
       .filter((file) => !isSkip(file)) as PageData[],
     outputDir,
     (file: PageData) => {
-      Logger.logSingle(`${file.fileName} processed.`, false, 'green', false);
+      Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
     },
   );
 }

package/src/application/generators/openapi.ts

@@ -7,10 +7,10 @@ import { Logger } from '#utils/logger';
 import ErrorLogger from '#utils/error-logger';
 import { reflect, ReflectionResult } from '@cparra/apex-reflection';
 import Manifest from '../../core/manifest';
-import { PageData, SourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
+import { PageData, UnparsedSourceFile, UserDefinedOpenApiConfig } from '../../core/shared/types';
 import { OpenApiDocsProcessor } from '../../core/openapi/open-api-docs-processor';
 
-export default function openApi(fileBodies: SourceFile[], config: UserDefinedOpenApiConfig) {
+export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDefinedOpenApiConfig) {
   const manifest = createManifest(new RawBodyParser(fileBodies), reflectionWithLogger);
   TypesRepository.getInstance().populateAll(manifest.types);
   const filteredTypes = filterByScopes(manifest);
@@ -19,14 +19,14 @@ export default function openApi(fileBodies: SourceFile[], config: UserDefinedOpe
   const generatedFiles = processor.fileBuilder().files();
 
   FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.fileName} processed.`, false, 'green', false);
+    Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
   });
 
   // Error logging
   ErrorLogger.logErrors(filteredTypes);
 }
 
-function reflectionWithLogger(apexBundle: SourceFile): ReflectionResult {
+function reflectionWithLogger(apexBundle: UnparsedSourceFile): ReflectionResult {
   const result = reflect(apexBundle.content);
   if (result.error) {
     Logger.error(`${apexBundle.filePath} - Parsing error ${result.error?.message}`);

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

@@ -12,7 +12,7 @@ describe('Generates interface documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].fileName).toBe('MyClass'));
+      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyClass'));
     });
 
     it('returns the type as class', async () => {
@@ -268,7 +268,9 @@ 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](./ClassRef.md) reference'),
+          expect(data).firstDocContains(
+            'This is a description with a [ClassRef](/miscellaneous/ClassRef.md) reference',
+          ),
         );
       });
 
@@ -302,7 +304,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](./ClassRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[ClassRef](/miscellaneous/ClassRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {
@@ -340,11 +342,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public class MyClass {}
           `;
@@ -359,11 +363,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @example
+            * \`\`\`apex
             * public class MyClass {
             *   public void myMethod() {
             *     System.debug('Hello, World!');
             *   }
             * }
+            * \`\`\`
             */
           public class MyClass {}`;
 
@@ -669,11 +675,13 @@ describe('Generates interface documentation', () => {
         public class MyClass {
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public void myMethod() {}
         }

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

@@ -17,7 +17,7 @@ describe('Generates enum documentation', () => {
 
       const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].fileName).toBe('MyEnum'));
+      assertEither(result, (data) => expect(data.docs[0].filePath).toContain('MyEnum'));
     });
 
     it('returns the type as enum', async () => {
@@ -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](./EnumRef.md) reference'),
+        expect(data).firstDocContains('This is a description with a [EnumRef](/miscellaneous/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](./EnumRef.md)'));
+      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](/miscellaneous/EnumRef.md)'));
     });
 
     it('displays sees without links when the reference is not found', async () => {
@@ -287,11 +287,13 @@ describe('Generates enum documentation', () => {
       const input = `
       /**
         * @mermaid
+        * \`\`\`mermaid
         * graph TD
         *   A[Square Rect] -- Link text --> B((Circle))
         *   A --> C(Round Rect)
         *   B --> D{Rhombus}
         *   C --> D
+        * \`\`\`
         */
       public enum MyEnum {
         VALUE1,
@@ -309,11 +311,13 @@ describe('Generates enum documentation', () => {
       const input = `
       /**
         * @example
+        * \`\`\`apex
         * public class MyClass {
         *   public void myMethod() {
         *     System.debug('Hello, World!');
         *   }
         * }
+        * \`\`\`
         */
       public enum MyEnum {
         VALUE1,

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

@@ -189,7 +189,9 @@ 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](./InterfaceRef.md) reference'),
+          expect(data).firstDocContains(
+            'This is a description with a [InterfaceRef](/miscellaneous/InterfaceRef.md) reference',
+          ),
         );
       });
 
@@ -223,7 +225,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](./InterfaceRef.md)'));
+        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](/miscellaneous/InterfaceRef.md)'));
       });
 
       it('displays sees without links when the reference is not found', async () => {
@@ -261,11 +263,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public interface MyInterface {}
           `;
@@ -280,11 +284,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @example
+            * \`\`\`apex
             * public class MyClass {
             *   public void myMethod() {
             *     System.debug('Hello, World!');
             *   }
             * }
+            * \`\`\`
             */
           public interface MyInterface {}`;
 
@@ -343,11 +349,13 @@ describe('Generates interface documentation', () => {
         public interface MyInterface {
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           void myMethod();
         }
@@ -445,7 +453,7 @@ describe('Generates interface documentation', () => {
         const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data.docs.find((doc) => doc.fileName === 'AnotherInterface')?.content).toContain('Inherited'),
+          expect(data.docs.find((doc) => doc.filePath.includes('AnotherInterface'))?.content).toContain('Inherited'),
         );
       });
     });

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

@@ -25,12 +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)'),
     );
   });
 
@@ -176,9 +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

@@ -1,8 +1,8 @@
-import { SourceFile } from '../../shared/types';
+import { UnparsedSourceFile } from '../../shared/types';
 import { generateDocs as gen, MarkdownGeneratorConfig } from '../generate-docs';
 import { referenceGuideTemplate } from '../templates/reference-guide';
 
-export function apexBundleFromRawString(raw: string, rawMetadata?: string): SourceFile {
+export function apexBundleFromRawString(raw: string, rawMetadata?: string): UnparsedSourceFile {
   return {
     filePath: 'test.cls',
     content: raw,
@@ -10,7 +10,7 @@ export function apexBundleFromRawString(raw: string, rawMetadata?: string): Sour
   };
 }
 
-export function generateDocs(apexBundles: SourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
+export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
   return gen(apexBundles, {
     targetDir: 'target',
     scope: ['global', 'public'],

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

@@ -21,7 +21,14 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
   it('converts the name', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
     const interfaceSource = typeToRenderable(
-      { filePath: '', type: interfaceMirror },
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
       linkGenerator,
       defaultMarkdownGeneratorConfig,
     );
@@ -32,7 +39,14 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
   it('converts the access modifier', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().build();
     const interfaceSource = typeToRenderable(
-      { filePath: '', type: interfaceMirror },
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
       linkGenerator,
       defaultMarkdownGeneratorConfig,
     );
@@ -45,7 +59,14 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
       .build();
     const interfaceSource = typeToRenderable(
-      { filePath: '', type: interfaceMirror },
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
       linkGenerator,
       defaultMarkdownGeneratorConfig,
     );
@@ -67,7 +88,14 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       .build();
 
     const interfaceSource = typeToRenderable(
-      { filePath: '', type: interfaceMirror },
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
       linkGenerator,
       defaultMarkdownGeneratorConfig,
     );
@@ -99,7 +127,14 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       .build();
 
     const interfaceSource = typeToRenderable(
-      { filePath: '', type: interfaceMirror },
+      {
+        source: {
+          filePath: '',
+          type: 'interface',
+          name: 'SampleInterface',
+        },
+        type: interfaceMirror,
+      },
       linkGenerator,
       defaultMarkdownGeneratorConfig,
     );

package/src/core/markdown/adapters/apex-types.ts

@@ -15,6 +15,7 @@ import { adaptDescribable, adaptDocumentable } from './documentables';
 import { adaptConstructor, adaptMethod } from './methods-and-constructors';
 import { adaptFieldOrProperty } from './fields-and-properties';
 import { MarkdownGeneratorConfig } from '../generate-docs';
+import { SourceFileMetadata } from '../../shared/types';
 
 type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
   ? RenderableInterface
@@ -23,7 +24,7 @@ type GetReturnRenderable<T extends Type> = T extends InterfaceMirror
     : RenderableEnum;
 
 export function typeToRenderable<T extends Type>(
-  parsedFile: { filePath: string; type: T },
+  parsedFile: { source: SourceFileMetadata; type: T },
   linkGenerator: GetRenderableContentByTypeName,
   config: MarkdownGeneratorConfig,
 ): GetReturnRenderable<T> & { filePath: string; namespace?: string } {
@@ -41,7 +42,7 @@ export function typeToRenderable<T extends Type>(
 
   return {
     ...(getRenderable() as GetReturnRenderable<T>),
-    filePath: parsedFile.filePath,
+    filePath: parsedFile.source.filePath,
     namespace: config.namespace,
   };
 }

package/src/core/markdown/adapters/documentables.ts

@@ -1,4 +1,4 @@
-import { CustomTag, RenderableDocumentation, RenderableContent, CodeBlock } from './types';
+import { CustomTag, RenderableDocumentation, RenderableContent } from './types';
 import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
 import { replaceInlineReferences } from './inline';
 import { isEmptyLine } from './type-utils';
@@ -9,59 +9,62 @@ export function adaptDescribable(
 ): {
   description?: RenderableContent[];
 } {
-  function describableToRenderableContent(describable: Describable): RenderableContent[] | undefined {
-    if (!describable) {
-      return;
-    }
+  return {
+    description: describableToRenderableContent(describable, linkGenerator),
+  };
+}
 
-    let content: RenderableContent[] = [];
-    for (let i = 0; i < describable.length; i++) {
-      const line = describable[i];
-      // The language might or might not be present after ```
-      const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
-      if (codeBlockMatch) {
-        // Check if the language is present, if not, fallback to "apex"
-        const language = codeBlockMatch[1] || 'apex';
-        const codeBlockLines: string[] = [];
-        i++;
-        while (i < describable.length) {
-          const currentLine = describable[i];
-          if (currentLine.trim() === '```') {
-            break;
-          }
-          codeBlockLines.push(currentLine);
-          i++;
+export function describableToRenderableContent(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): RenderableContent[] | undefined {
+  if (!describable) {
+    return;
+  }
+
+  let content: RenderableContent[] = [];
+  for (let i = 0; i < describable.length; i++) {
+    const line = describable[i];
+    // The language might or might not be present after ```
+    const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+    if (codeBlockMatch) {
+      // Check if the language is present, if not, fallback to "apex"
+      const language = codeBlockMatch[1] || 'apex';
+      const codeBlockLines: string[] = [];
+      i++;
+      while (i < describable.length) {
+        const currentLine = describable[i];
+        if (currentLine.trim() === '```') {
+          break;
         }
-        content = [
-          ...content,
-          {
-            __type: 'code-block',
-            language,
-            content: codeBlockLines,
-          },
-          { __type: 'empty-line' },
-        ];
-        continue;
+        codeBlockLines.push(currentLine);
+        i++;
       }
-
       content = [
         ...content,
-        ...replaceInlineReferences(line, linkGenerator),
         {
-          __type: 'empty-line',
+          __type: 'code-block',
+          language,
+          content: codeBlockLines,
         },
+        { __type: 'empty-line' },
       ];
+      continue;
     }
-    return (
-      content
-        // If the last element is an empty line, remove it
-        .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
-    );
-  }
 
-  return {
-    description: describableToRenderableContent(describable),
-  };
+    content = [
+      ...content,
+      ...replaceInlineReferences(line, linkGenerator),
+      {
+        __type: 'empty-line',
+      },
+    ];
+  }
+  return (
+    content
+      // If the last element is an empty line, remove it
+      .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
+  );
 }
 
 export function adaptDocumentable(
@@ -70,7 +73,7 @@ export function adaptDocumentable(
   subHeadingLevel: number,
 ): RenderableDocumentation {
   function extractCustomTags(type: Documentable): CustomTag[] {
-    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'mermaid', 'throws', 'exception'];
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'throws', 'exception'];
 
     return (
       type.docComment?.annotations
@@ -82,12 +85,6 @@ export function adaptDocumentable(
     );
   }
 
-  function extractAnnotationBodyLines(type: Documentable, annotationName: string): string[] | undefined {
-    return type.docComment?.annotations.find(
-      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
-    )?.bodyLines;
-  }
-
   function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
     return type.docComment?.annotations.find(
       (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
@@ -102,30 +99,14 @@ export function adaptDocumentable(
     );
   }
 
-  function bodyLinesToCodeBlock(language: string, bodyLines: string[] | undefined): CodeBlock | undefined {
-    if (!bodyLines) {
-      return;
-    }
-    return {
-      __type: 'code-block',
-      language,
-      content: bodyLines,
-    };
-  }
-
   return {
     ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
-    mermaid: {
-      headingLevel: subHeadingLevel,
-      heading: 'Diagram',
-      value: bodyLinesToCodeBlock('mermaid', extractAnnotationBodyLines(documentable, 'mermaid')),
-    },
     example: {
       headingLevel: subHeadingLevel,
       heading: 'Example',
-      value: bodyLinesToCodeBlock('apex', documentable.docComment?.exampleAnnotation?.bodyLines),
+      value: describableToRenderableContent(documentable.docComment?.exampleAnnotation?.bodyLines, linkGenerator),
     },
     group: extractAnnotationBody(documentable, 'group'),
     author: extractAnnotationBody(documentable, 'author'),

package/src/core/markdown/adapters/reference-guide.ts

@@ -0,0 +1,35 @@
+import { MarkdownGeneratorConfig } from '../generate-docs';
+import { DocPageReference, ParsedFile } from '../../shared/types';
+import { Type } from '@cparra/apex-reflection';
+
+export function parsedFilesToReferenceGuide(
+  config: MarkdownGeneratorConfig,
+  parsedFiles: ParsedFile[],
+): Record<string, DocPageReference> {
+  return parsedFiles.reduce<Record<string, DocPageReference>>((acc, parsedFile) => {
+    acc[parsedFile.type.name] = parsedFileToDocPageReference(config, parsedFile);
+    return acc;
+  }, {});
+}
+
+function parsedFileToDocPageReference(config: MarkdownGeneratorConfig, parsedFile: ParsedFile): DocPageReference {
+  return {
+    source: parsedFile.source,
+    displayName: parsedFile.type.name,
+    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`,
+  };
+}
+
+function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
+  const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
+  return groupAnnotation?.body ?? config.defaultGroupName;
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '') // Remove non-alphanumeric characters except spaces and hyphens
+    .trim()
+    .replace(/\s+/g, '-') // Replace spaces with hyphens
+    .replace(/-+/g, '-'); // Replace multiple hyphens with a single hyphen
+}