@cparra/apexdocs 3.0.0-alpha.1 → 3.0.0-alpha.2

package/dist/cli/generate.js

@@ -611,7 +611,7 @@ const linkGenerator = (references, documentationRootDir, referenceName) => {
     {
       __type: "link",
       title: reference.displayName,
-      url: path__namespace.join("/", documentationRootDir, reference.pathFromRoot)
+      url: path__namespace.join("/", documentationRootDir, reference.referencePath)
     }
   ) : referenceName;
 };
@@ -1198,7 +1198,7 @@ const convertToDocumentationBundle = (referenceGuideTemplate, { referencesByGrou
   referenceGuide: {
     frontmatter: null,
     content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
-    filePath: "index.md"
+    outputDocPath: "index.md"
   },
   docs: renderables.map(
     (renderable) => renderableToPageData(Object.values(referencesByGroup).flat(), renderable)
@@ -1232,7 +1232,7 @@ function renderableToPageData(referenceGuideReference, renderable) {
         name: renderable2.name,
         type: renderable2.type
       },
-      filePath: reference.reference.pathFromRoot,
+      outputDocPath: reference.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
       group: (_a = renderable2.doc.group) != null ? _a : defaults.defaults.defaultGroupName
@@ -1450,10 +1450,12 @@ function parsedFilesToReferenceGuide(config, parsedFiles) {
   }, {});
 }
 function parsedFileToDocPageReference(config, parsedFile) {
+  const path = `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`;
   return {
     source: parsedFile.source,
     displayName: parsedFile.type.name,
-    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`
+    outputDocPath: path,
+    referencePath: path
   };
 }
 function getTypeGroup(type, config) {
@@ -1645,15 +1647,15 @@ var __spreadProps$6 = (a, b) => __defProps$6(a, __getOwnPropDescs$6(b));
 class FileWriter {
   static write(files, outputDir, onWriteCallback) {
     files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs__namespace.mkdirSync(path__namespace.dirname(filePath), { recursive: true });
-      fs__namespace.writeFileSync(filePath, content, "utf8");
+      const { outputDocPath, content } = this.getTargetLocation(file, outputDir);
+      fs__namespace.mkdirSync(path__namespace.dirname(outputDocPath), { recursive: true });
+      fs__namespace.writeFileSync(outputDocPath, content, "utf8");
       onWriteCallback(file);
     });
   }
   static getTargetLocation(file, outputDir) {
     return __spreadProps$6(__spreadValues$6({}, file), {
-      filePath: path__namespace.join(outputDir, file.filePath)
+      outputDocPath: path__namespace.join(outputDir, file.outputDocPath)
     });
   }
 }
@@ -1769,7 +1771,7 @@ function writeFilesToSystem(files, outputDir) {
     [files.referenceGuide, ...files.docs].filter((file) => !isSkip(file)),
     outputDir,
     (file) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
+      Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
     }
   );
 }
@@ -2654,7 +2656,7 @@ var __spreadProps$1 = (a, b) => __defProps$1(a, __getOwnPropDescs$1(b));
 function createOpenApiFile(fileName, openApiModel) {
   const content = JSON.stringify(__spreadProps$1(__spreadValues$1({}, openApiModel), { namespace: void 0 }), null, 2);
   return {
-    filePath: "",
+    outputDocPath: "",
     content,
     frontmatter: null,
     group: null
@@ -2727,7 +2729,7 @@ function openApi(fileBodies, config) {
   Transpiler.generate(filteredTypes, processor);
   const generatedFiles = processor.fileBuilder().files();
   FileWriter.write(generatedFiles, config.targetDir, (file) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, "green", false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, false, "green", false);
   });
   ErrorLogger.logErrors(filteredTypes);
 }

package/dist/index.d.ts

@@ -33,8 +33,13 @@ type DocPageReference = {
   // The name under which the type should be displayed in the documentation.
   // By default, this will match the source.name, but it can be configured by the user.
   displayName: string;
-  // The location of the file relative to the root of the documentation.
-  pathFromRoot: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
 };
 
 type Frontmatter = string | Record<string, unknown> | null;
@@ -42,13 +47,13 @@ type Frontmatter = string | Record<string, unknown> | null;
 type ReferenceGuidePageData = {
   frontmatter: Frontmatter;
   content: string;
-  filePath: string;
+  outputDocPath: string;
 };
 
 type DocPageData = {
   source: SourceFileMetadata;
   group: string | null;
-  filePath: string;
+  outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -64,7 +69,7 @@ type Skip = {
 
 type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.

package/examples/vitepress/apexdocs.config.ts

@@ -86,7 +86,7 @@ export default defineMarkdownConfig({
 function toSidebarLink(doc: DocPageData) {
   return {
     text: doc.source.name,
-    link: doc.filePath,
+    link: doc.outputDocPath,
   };
 }
 

package/package.json

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

package/src/application/file-writer.ts

@@ -5,9 +5,9 @@ import { PageData } from '../core/shared/types';
 export class FileWriter {
   static write(files: PageData[], outputDir: string, onWriteCallback: (file: PageData) => void) {
     files.forEach((file) => {
-      const { filePath, content } = this.getTargetLocation(file, outputDir);
-      fs.mkdirSync(path.dirname(filePath), { recursive: true });
-      fs.writeFileSync(filePath, content, 'utf8');
+      const { outputDocPath, content } = this.getTargetLocation(file, outputDir);
+      fs.mkdirSync(path.dirname(outputDocPath), { recursive: true });
+      fs.writeFileSync(outputDocPath, content, 'utf8');
       onWriteCallback(file);
     });
   }
@@ -15,7 +15,7 @@ export class FileWriter {
   private static getTargetLocation(file: PageData, outputDir: string): PageData {
     return {
       ...file,
-      filePath: path.join(outputDir, file.filePath),
+      outputDocPath: path.join(outputDir, file.outputDocPath),
     };
   }
 }

package/src/application/generators/markdown.ts

@@ -48,7 +48,7 @@ function writeFilesToSystem(files: PostHookDocumentationBundle, outputDir: strin
       .filter((file) => !isSkip(file)) as PageData[],
     outputDir,
     (file: PageData) => {
-      Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
+      Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
     },
   );
 }

package/src/application/generators/openapi.ts

@@ -19,7 +19,7 @@ export default function openApi(fileBodies: UnparsedSourceFile[], config: UserDe
   const generatedFiles = processor.fileBuilder().files();
 
   FileWriter.write(generatedFiles, config.targetDir, (file: PageData) => {
-    Logger.logSingle(`${file.filePath} processed.`, false, 'green', false);
+    Logger.logSingle(`${file.outputDocPath} processed.`, false, 'green', false);
   });
 
   // Error logging

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].filePath).toContain('MyClass'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyClass'));
     });
 
     it('returns the type as class', async () => {

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].filePath).toContain('MyEnum'));
+      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyEnum'));
     });
 
     it('returns the type as enum', async () => {

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

@@ -453,7 +453,9 @@ 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.filePath.includes('AnotherInterface'))?.content).toContain('Inherited'),
+          expect(data.docs.find((doc) => doc.outputDocPath.includes('AnotherInterface'))?.content).toContain(
+            'Inherited',
+          ),
         );
       });
     });

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

@@ -13,10 +13,12 @@ export function parsedFilesToReferenceGuide(
 }
 
 function parsedFileToDocPageReference(config: MarkdownGeneratorConfig, parsedFile: ParsedFile): DocPageReference {
+  const path = `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`;
   return {
     source: parsedFile.source,
     displayName: parsedFile.type.name,
-    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`,
+    outputDocPath: path,
+    referencePath: path,
   };
 }
 

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

@@ -67,7 +67,7 @@ const linkGenerator = (
       {
         __type: 'link',
         title: reference.displayName,
-        url: path.join('/', documentationRootDir, reference.pathFromRoot),
+        url: path.join('/', documentationRootDir, reference.referencePath),
       }
     : referenceName;
 };

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -14,7 +14,7 @@ export const convertToDocumentationBundle = (
   referenceGuide: {
     frontmatter: null,
     content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
-    filePath: 'index.md',
+    outputDocPath: 'index.md',
   },
   docs: renderables.map((renderable: Renderable) =>
     renderableToPageData(Object.values(referencesByGroup).flat(), renderable),
@@ -56,7 +56,7 @@ function renderableToPageData(referenceGuideReference: ReferenceGuideReference[]
         name: renderable.name,
         type: renderable.type,
       },
-      filePath: reference!.reference.pathFromRoot,
+      outputDocPath: reference!.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
       group: renderable.doc.group ?? defaults.defaultGroupName,

package/src/core/openapi/openapi-type-file.ts

@@ -4,7 +4,7 @@ import { OpenApiPageData } from '../shared/types';
 export function createOpenApiFile(fileName: string, openApiModel: OpenApi): OpenApiPageData {
   const content = JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2);
   return {
-    filePath: '',
+    outputDocPath: '',
     content,
     frontmatter: null,
     group: null,

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

@@ -55,8 +55,13 @@ export type DocPageReference = {
   // The name under which the type should be displayed in the documentation.
   // By default, this will match the source.name, but it can be configured by the user.
   displayName: string;
-  // The location of the file relative to the root of the documentation.
-  pathFromRoot: string;
+  // The location where the file will be written.
+  outputDocPath: string;
+  // The path to the file relative to the documentation root directory. This is used when linking to the file.
+  // Usually the value will be the same as outputDocPath. However, some site generators may have a different way of
+  // organizing the files, so this allows for the flexibility of having a path from linking that is different from
+  // the path where the file is written.
+  referencePath: string;
 };
 
 type Frontmatter = string | Record<string, unknown> | null;
@@ -64,13 +69,13 @@ type Frontmatter = string | Record<string, unknown> | null;
 export type ReferenceGuidePageData = {
   frontmatter: Frontmatter;
   content: string;
-  filePath: string;
+  outputDocPath: string;
 };
 
 export type DocPageData = {
   source: SourceFileMetadata;
   group: string | null;
-  filePath: string;
+  outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -100,7 +105,7 @@ export type PostHookDocumentationBundle = {
 
 type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.