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

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

@@ -4,9 +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 {
-    fileExtension: 'json',
-    fileName,
-    directory: '',
+    filePath: '',
     content,
     frontmatter: null,
     group: null,

package/src/core/openapi/parser.ts

@@ -1,18 +1,18 @@
 import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
 import { parseApexMetadata } from '../parse-apex-metadata';
 import { Logger } from '#utils/logger';
-import { SourceFile } from '../shared/types';
+import { UnparsedSourceFile } from '../shared/types';
 
 export interface TypeParser {
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[];
+  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[];
 }
 
 type NameAware = { name: string };
 
 export class RawBodyParser implements TypeParser {
-  constructor(public typeBundles: SourceFile[]) {}
+  constructor(public typeBundles: UnparsedSourceFile[]) {}
 
-  parse(reflect: (apexBundle: SourceFile) => ReflectionResult): Type[] {
+  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[] {
     const types = this.typeBundles
       .map((currentBundle) => {
         Logger.log(`Parsing file: ${currentBundle.filePath}`);

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

@@ -2,10 +2,14 @@ import { Type } from '@cparra/apex-reflection';
 
 export type Generator = 'markdown' | 'openapi';
 
+/**
+ * The configurable hooks that can be used to modify the output of the generator.
+ */
 export type ConfigurableHooks = {
   transformReferenceGuide: TransformReferenceGuide;
   transformDocs: TransformDocs;
   transformDocPage: TransformDocPage;
+  transformReference: TransformReference;
 };
 
 export type UserDefinedMarkdownConfig = {
@@ -28,37 +32,44 @@ export type UserDefinedOpenApiConfig = {
 
 export type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig;
 
-export type SourceFile = {
+export type UnparsedSourceFile = {
   filePath: string;
   content: string;
   metadataContent: string | null;
 };
 
-export type ParsedFile = {
+export type SourceFileMetadata = {
   filePath: string;
+  name: string;
+  type: 'interface' | 'class' | 'enum';
+};
+
+export type ParsedFile = {
+  source: SourceFileMetadata;
   type: Type;
 };
 
+export type DocPageReference = {
+  source: SourceFileMetadata;
+  // 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;
+};
+
 type Frontmatter = string | Record<string, unknown> | null;
 
 export type ReferenceGuidePageData = {
-  directory: string;
   frontmatter: Frontmatter;
   content: string;
-  fileExtension: string;
-  fileName: string;
+  filePath: string;
 };
 
 export type DocPageData = {
-  source: {
-    filePath: string;
-    name: string;
-    type: 'interface' | 'class' | 'enum';
-  };
+  source: SourceFileMetadata;
   group: string | null;
-  fileName: string;
-  fileExtension: string;
-  directory: string;
+  filePath: string;
   frontmatter: Frontmatter;
   content: string;
 };
@@ -72,6 +83,9 @@ export type DocumentationBundle = {
   docs: DocPageData[];
 };
 
+/**
+ * Represents a file to be skipped.
+ */
 export type Skip = {
   readonly _tag: 'Skip';
 };
@@ -83,10 +97,34 @@ export type PostHookDocumentationBundle = {
 
 // Configurable Hooks
 
+type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
+
+type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'filePath'>;
+
+/**
+ * Allows changing where the files are written to.
+ */
+export type TransformReference = (
+  reference: DocPageReference,
+) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;
+
+/**
+ * Allows changing the frontmatter and content of the reference guide, or even if creating a reference
+ * guide will be skipped altogether.
+ */
 export type TransformReferenceGuide = (
   referenceGuide: ReferenceGuidePageData,
 ) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
 
+/**
+ * The main purpose if for allowing for doc pages to be skipped, but it can also be used to change the frontmatter
+ * and content of the doc pages.
+ */
 export type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>;
 
-export type TransformDocPage = (doc: DocPageData) => Partial<DocPageData> | Promise<Partial<DocPageData>>;
+/**
+ * Allows changing the frontmatter and content of the doc pages.
+ */
+export type TransformDocPage = (
+  doc: DocPageData,
+) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;

package/src/index.ts

@@ -5,6 +5,7 @@ import type {
   UserDefinedMarkdownConfig,
   ReferenceGuidePageData,
   DocPageData,
+  DocPageReference,
 } from './core/shared/types';
 import { defaults } from './defaults';
 
@@ -32,4 +33,4 @@ function skip(): Skip {
 
 // Exports
 
-export { defineMarkdownConfig, skip, ConfigurableHooks, ReferenceGuidePageData, DocPageData };
+export { defineMarkdownConfig, skip, ConfigurableHooks, ReferenceGuidePageData, DocPageData, DocPageReference };

package/examples/plain-markdown/docs/Sample-Enums/ns.SampleEnum.md

@@ -1,38 +0,0 @@
-# SampleEnum Enum
-
-`NAMESPACEACCESSIBLE`
-
-This is a sample enum. This references [ns.ReferencedEnum](../Miscellaneous/ns.ReferencedEnum.md) . 
-
-This description has several lines
-
-**Some Custom** 
-
-Test. I can also have a [ns.ReferencedEnum](../Miscellaneous/ns.ReferencedEnum.md) here. 
-
-And it can be multiline.
-
-**Group** Sample Enums
-
-**Author** John Doe
-
-**Date** 2022-01-01
-
-**See** [ns.ReferencedEnum](../Miscellaneous/ns.ReferencedEnum.md)
-
-## Namespace
-ns
-
-## Diagram
-```mermaid
-graph TD
- A[SampleEnum] -->|references| B[ReferencedEnum]
- B -->|referenced by| A
-```
-
-## Values
-| Value | Description |
-|-------|-------------|
-| VALUE1 | This is value 1 |
-| VALUE2 | This is value 2 |
-| VALUE3 | This is value 3 |