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

package/src/core/settings.ts

@@ -0,0 +1,56 @@
+import { Generator } from './shared/types';
+
+export interface SettingsConfig {
+  sourceDirectory: string;
+  scope: string[];
+  outputDir: string;
+  targetGenerator: Generator;
+  indexOnly: boolean;
+  defaultGroupName: string;
+  openApiTitle?: string;
+  namespace?: string;
+  openApiFileName: string;
+  includeMetadata: boolean;
+  sortMembersAlphabetically?: boolean;
+}
+
+export class Settings {
+  private static instance: Settings;
+
+  private constructor(public config: SettingsConfig) {}
+
+  public static build(config: SettingsConfig) {
+    Settings.instance = new Settings(config);
+  }
+
+  public static getInstance(): Settings {
+    if (!Settings.instance) {
+      throw new Error('Settings has not been initialized');
+    }
+    return Settings.instance;
+  }
+
+  get scope(): string[] {
+    return this.config.scope;
+  }
+
+  get targetGenerator(): Generator {
+    return this.config.targetGenerator;
+  }
+
+  get indexOnly(): boolean {
+    return this.config.indexOnly;
+  }
+
+  public getOpenApiTitle(): string | undefined {
+    return this.config.openApiTitle;
+  }
+
+  public getNamespace(): string | undefined {
+    return this.config.namespace;
+  }
+
+  public openApiFileName(): string {
+    return this.config.openApiFileName;
+  }
+}

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

@@ -0,0 +1,92 @@
+import { Type } from '@cparra/apex-reflection';
+
+export type Generator = 'markdown' | 'openapi';
+
+export type ConfigurableHooks = {
+  transformReferenceGuide: TransformReferenceGuide;
+  transformDocs: TransformDocs;
+  transformDocPage: TransformDocPage;
+};
+
+export type UserDefinedMarkdownConfig = {
+  targetGenerator: 'markdown';
+  sourceDir: string;
+  targetDir: string;
+  scope: string[];
+  defaultGroupName: string;
+  namespace?: string;
+  sortMembersAlphabetically: boolean;
+  includeMetadata: boolean;
+} & Partial<ConfigurableHooks>;
+
+export type UserDefinedOpenApiConfig = {
+  targetGenerator: 'openapi';
+  sourceDir: string;
+  targetDir: string;
+  includeMetadata: boolean;
+};
+
+export type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig;
+
+export type SourceFile = {
+  filePath: string;
+  content: string;
+  metadataContent: string | null;
+};
+
+export type ParsedFile = {
+  filePath: string;
+  type: Type;
+};
+
+type Frontmatter = string | Record<string, unknown> | null;
+
+export type ReferenceGuidePageData = {
+  directory: string;
+  frontmatter: Frontmatter;
+  content: string;
+  fileExtension: string;
+  fileName: string;
+};
+
+export type DocPageData = {
+  source: {
+    filePath: string;
+    name: string;
+    type: 'interface' | 'class' | 'enum';
+  };
+  group: string | null;
+  fileName: string;
+  fileExtension: string;
+  directory: string;
+  frontmatter: Frontmatter;
+  content: string;
+};
+
+export type OpenApiPageData = Omit<DocPageData, 'source'>;
+
+export type PageData = DocPageData | OpenApiPageData | ReferenceGuidePageData;
+
+export type DocumentationBundle = {
+  referenceGuide: ReferenceGuidePageData;
+  docs: DocPageData[];
+};
+
+export type Skip = {
+  readonly _tag: 'Skip';
+};
+
+export type PostHookDocumentationBundle = {
+  referenceGuide: ReferenceGuidePageData | Skip;
+  docs: DocPageData[];
+};
+
+// Configurable Hooks
+
+export type TransformReferenceGuide = (
+  referenceGuide: ReferenceGuidePageData,
+) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
+
+export type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;
+
+export type TransformDocPage = (doc: DocPageData) => Partial<DocPageData> | Promise<Partial<DocPageData>>;

package/src/core/shared/utils.ts

@@ -0,0 +1,5 @@
+import { Skip } from './types';
+
+export function isSkip(value: unknown): value is Skip {
+  return Object.prototype.hasOwnProperty.call(value, '_tag') && (value as Skip)._tag === 'Skip';
+}

package/src/defaults.ts

@@ -0,0 +1,8 @@
+export const defaults = {
+  targetGenerator: 'markdown' as const,
+  targetDir: './docs/',
+  scope: ['global'],
+  defaultGroupName: 'Miscellaneous',
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+};

package/src/index.ts

@@ -1,3 +1,35 @@
-import * as reflection from '@cparra/apex-reflection';
+import { SetOptional } from 'type-fest';
+import type {
+  ConfigurableHooks,
+  Skip,
+  UserDefinedMarkdownConfig,
+  ReferenceGuidePageData,
+  DocPageData,
+} from './core/shared/types';
+import { defaults } from './defaults';
 
-export { reflection };
+type ConfigurableMarkdownConfig = Omit<
+  SetOptional<
+    UserDefinedMarkdownConfig,
+    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'
+  >,
+  'targetGenerator'
+>;
+
+function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig {
+  return {
+    ...defaults,
+    ...config,
+    targetGenerator: 'markdown',
+  };
+}
+
+function skip(): Skip {
+  return {
+    _tag: 'Skip',
+  };
+}
+
+// Exports
+
+export { defineMarkdownConfig, skip, ConfigurableHooks, ReferenceGuidePageData, DocPageData };

package/src/test-helpers/InterfaceMirrorBuilder.ts

@@ -20,11 +20,6 @@ export class InterfaceMirrorBuilder {
     return this;
   }
 
-  withDocComment(docComment: DocComment): InterfaceMirrorBuilder {
-    this.docComment = docComment;
-    return this;
-  }
-
   addMethod(method: MethodMirror): InterfaceMirrorBuilder {
     this.methods.push(method);
     return this;

package/src/test-helpers/SettingsBuilder.ts

@@ -1,4 +1,4 @@
-import { SettingsConfig } from '../settings';
+import { SettingsConfig } from '../core/settings';
 
 /**
  * Builder class to create SettingsConfig objects.
@@ -15,9 +15,7 @@ export class SettingsBuilder {
       defaultGroupName: 'Misc',
       openApiTitle: 'Apex API',
       openApiFileName: 'openapi',
-      title: 'Classes',
       includeMetadata: false,
-      linkingStrategy: 'root-relative',
     };
   }
 }

package/src/util/logger.ts

@@ -26,14 +26,14 @@ export class Logger {
    * @param message The error message to log.
    * @param args Optional arguments.
    */
-  public static error(message: string, ...args: string[]) {
+  public static error(message: unknown, ...args: string[]) {
     this.logSingle(message, false, 'red', false);
     args.forEach(() => {
       this.logSingle(message, false, 'red', false);
     });
   }
 
-  public static logSingle(text: string, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
+  public static logSingle(text: unknown, showSpinner = true, color: 'green' | 'red' = 'green', overrideConsole = true) {
     if (this.currentFrame > 9) {
       this.currentFrame = 0;
     }

package/src/util/string-utils.ts

@@ -1,7 +1,3 @@
-export function truncate(str: string, n: number) {
-  return str.length > n ? str.substr(0, n - 1) + '…' : str;
-}
-
 export const camel2title = (camelCase: string) =>
   camelCase
     .replace(/\//g, ' ')

package/tsconfig.json

@@ -9,7 +9,11 @@
     "esModuleInterop": true,
     "lib": [
       "ES2021"
-    ]
+    ],
+    "baseUrl": "./",
+    "paths": {
+      "#utils/*": ["src/util/*"],
+    }
   },
   "include": [
     "src", "jest.d.ts"

package/apexdocs.config.ts

@@ -1,13 +0,0 @@
-import { TargetFile, TargetType } from './src/settings';
-
-export default {
-  onBeforeFileWrite: (file: TargetFile): TargetFile => {
-    console.log('onBefore writing', file);
-    return file;
-  },
-  onAfterProcess: (files: TargetFile[]) => {
-    console.log('onAfterProcess files', files);
-  },
-  frontMatterHeader: (file: TargetType) => [`title: ${file.name}.cls`, `description: ${file.description}`],
-  sortMembersAlphabetically: true,
-};

package/examples/plain-markdown/template.md

@@ -1,3 +0,0 @@
-# Template file
-
-{{{api_docs}}}