@cparra/apexdocs 2.25.0-alpha.0 → 2.25.0-alpha.10

package/src/templating/compile.ts

@@ -1,187 +0,0 @@
-import Handlebars from 'handlebars';
-import {
-  EnumSource,
-  ConvertRenderableContentsToString,
-  InterfaceSource,
-  ClassSource,
-  MethodSource,
-  RenderableContent,
-  DocumentableSource,
-} from './types';
-import { namespace, splitAndCapitalize } from './helpers';
-import { typeLevelApexDocPartialTemplate } from '../transpiler/markdown/plain-markdown/type-level-apex-doc-partial-template';
-import { methodsPartialTemplate } from '../transpiler/markdown/plain-markdown/methods-partial-template';
-import { constructorsPartialTemplate } from '../transpiler/markdown/plain-markdown/constructors-partial-template';
-import { fieldsPartialTemplate } from '../transpiler/markdown/plain-markdown/fieldsPartialTemplate';
-import { documentablePartialTemplate } from '../transpiler/markdown/plain-markdown/documentable-partial-template';
-
-type CompileOptions = {
-  renderableContentConverter: ConvertRenderableContentsToString;
-  codeBlockConverter: (language: string, lines: string[]) => string;
-};
-
-export function compile(template: string, source: EnumSource | InterfaceSource | ClassSource, options: CompileOptions) {
-  Handlebars.registerPartial('typeLevelApexDocPartialTemplate', typeLevelApexDocPartialTemplate);
-  Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
-  Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
-  Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
-  Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
-
-  Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
-
-  const prepared = { ...prepare(source, options), namespace: namespace() };
-  const compiled = Handlebars.compile(template);
-  return (
-    compiled(prepared)
-      .trim()
-      // clean up extra newlines
-      .replace(/\n{3,}/g, '\n\n')
-  );
-}
-
-function prepare(
-  source: EnumSource | InterfaceSource | ClassSource,
-  { renderableContentConverter, codeBlockConverter }: CompileOptions,
-) {
-  const base = {
-    ...source,
-    ...prepareDocumentable(source, renderableContentConverter, codeBlockConverter),
-    ...prepareBaseType(source, renderableContentConverter),
-  };
-  if (isEnumSource(source)) {
-    return {
-      ...base,
-      ...prepareEnum(source, renderableContentConverter),
-    };
-  } else if (isInterfaceSource(source)) {
-    return {
-      ...base,
-      ...prepareInterface(source, renderableContentConverter, codeBlockConverter),
-    };
-  } else {
-    return {
-      ...base,
-      ...prepareClass(source, renderableContentConverter, codeBlockConverter),
-    };
-  }
-}
-
-function prepareDocumentable(
-  source: DocumentableSource,
-  renderableContentConverter: ConvertRenderableContentsToString,
-  codeBlockConverter: (language: string, lines: string[]) => string,
-) {
-  return {
-    description: renderableContentConverter(source.description),
-    mermaid: source.mermaid ? codeBlockConverter('mermaid', source.mermaid) : undefined,
-    example: source.example ? codeBlockConverter('apex', source.example) : undefined,
-    customTags: source.customTags?.map((tag) => ({
-      name: tag.name,
-      value: renderableContentConverter(tag.description),
-    })),
-  };
-}
-
-function prepareBaseType(
-  source: EnumSource | InterfaceSource | ClassSource,
-  renderableContentConverter: ConvertRenderableContentsToString,
-) {
-  return {
-    sees: source.sees?.map((see) => renderableContentConverter([see])),
-  };
-}
-
-function prepareEnum(source: EnumSource, renderableContentConverter: ConvertRenderableContentsToString) {
-  return {
-    values: source.values.map((value) => ({
-      value: value.value,
-      description: renderableContentConverter(value.description),
-    })),
-  };
-}
-
-function prepareInterface(
-  source: InterfaceSource,
-  renderableContentConverter: ConvertRenderableContentsToString,
-  codeBlockConverter: (language: string, lines: string[]) => string,
-) {
-  return {
-    extends: source.extends?.map((ext) => renderableContentConverter([ext])),
-    methods: source.methods?.map((method) => mapMethod(method, renderableContentConverter, codeBlockConverter)),
-  };
-}
-
-function prepareClass(
-  source: ClassSource,
-  renderableContentConverter: ConvertRenderableContentsToString,
-  codeBlockConverter: (language: string, lines: string[]) => string,
-) {
-  return {
-    implements: source.implements?.map((impl) => renderableContentConverter([impl])),
-    extends: source.extends ? renderableContentConverter([source.extends]) : undefined,
-    constructors: source.constructors?.map((constructor) =>
-      mapConstructor(constructor, renderableContentConverter, codeBlockConverter),
-    ),
-    methods: source.methods?.map((method) => mapMethod(method, renderableContentConverter, codeBlockConverter)),
-    fields: source.fields?.map((field) => ({
-      ...field,
-      ...prepareDocumentable(field, renderableContentConverter, codeBlockConverter),
-      type: renderableContentConverter([field.type]),
-    })),
-  };
-}
-
-function mapMethod(
-  method: MethodSource,
-  renderableContentConverter: (content?: RenderableContent[]) => string,
-  codeBlockConverter: (language: string, lines: string[]) => string,
-) {
-  return {
-    ...method,
-    ...prepareDocumentable(method, renderableContentConverter, codeBlockConverter),
-    returnType: {
-      ...method,
-      type: method.returnType?.type ? renderableContentConverter([method.returnType.type]) : undefined,
-      description: renderableContentConverter(method.returnType?.description),
-    },
-    throws: method.throws?.map((thrown) => ({
-      ...thrown,
-      type: renderableContentConverter([thrown.type]),
-      description: renderableContentConverter(thrown.description),
-    })),
-    parameters: method.parameters?.map((param) => ({
-      ...param,
-      type: renderableContentConverter([param.type]),
-      description: renderableContentConverter(param.description),
-    })),
-  };
-}
-
-function mapConstructor(
-  constructor: MethodSource,
-  renderableContentConverter: (content?: RenderableContent[]) => string,
-  codeBlockConverter: (language: string, lines: string[]) => string,
-) {
-  return {
-    ...constructor,
-    ...prepareDocumentable(constructor, renderableContentConverter, codeBlockConverter),
-    parameters: constructor.parameters?.map((param) => ({
-      ...param,
-      type: renderableContentConverter([param.type]),
-      description: renderableContentConverter(param.description),
-    })),
-    throws: constructor.throws?.map((thrown) => ({
-      ...thrown,
-      type: renderableContentConverter([thrown.type]),
-      description: renderableContentConverter(thrown.description),
-    })),
-  };
-}
-
-function isEnumSource(source: { __type: string }): source is EnumSource {
-  return source.__type === 'enum';
-}
-
-function isInterfaceSource(source: { __type: string }): source is InterfaceSource {
-  return source.__type === 'interface';
-}

package/src/templating/helpers.ts

@@ -1,14 +0,0 @@
-import { Settings } from '../settings';
-
-export const splitAndCapitalize = (text: string) => {
-  const words = text.split(/[-_]+/);
-  const capitalizedWords = [];
-  for (const word of words) {
-    capitalizedWords.push(word.charAt(0).toUpperCase() + word.slice(1));
-  }
-  return capitalizedWords.join(' ');
-};
-
-export const namespace = () => {
-  return Settings.getInstance().getNamespace();
-};

package/src/templating/types.d.ts

@@ -1,104 +0,0 @@
-export type Link = {
-  title: string;
-  url: string;
-};
-
-export type EmptyLine = {
-  type: 'empty-line';
-};
-
-export type StringOrLink = string | Link;
-
-export type RenderableContent = StringOrLink | EmptyLine;
-
-export type ConvertRenderableContentsToString = (content?: RenderableContent[]) => string;
-
-type EnumValue = {
-  value: string;
-  description?: RenderableContent[];
-};
-
-type CustomTag = {
-  name: string;
-  description?: RenderableContent[];
-};
-
-/**
- * Represents an annotation to a top-level type. For example @NamespaceAccessible.
- */
-type Annotation = string;
-
-type CodeBlock = string[];
-
-type DocumentableSource = {
-  annotations?: Annotation[];
-  description?: RenderableContent[];
-  customTags?: CustomTag[];
-  mermaid?: CodeBlock;
-  example?: CodeBlock;
-};
-
-type BaseTypeSource = DocumentableSource & {
-  name: string;
-  accessModifier: string;
-  group?: string;
-  author?: string;
-  date?: string;
-  sees?: StringOrLink[];
-};
-
-type MethodParameterSource = {
-  name: string;
-  type: StringOrLink;
-  description?: RenderableContent[];
-};
-
-type TypeSource = {
-  type: StringOrLink;
-  description?: RenderableContent[];
-};
-
-type ConstructorSource = DocumentableSource & {
-  title: string;
-  signature: string;
-  parameters?: MethodParameterSource[];
-  throws?: TypeSource[];
-};
-
-type MethodSource = DocumentableSource & {
-  title: string;
-  signature: string;
-  parameters?: MethodParameterSource[];
-  returnType?: TypeSource;
-  throws?: TypeSource[];
-  inherited?: boolean;
-};
-
-type FieldSource = DocumentableSource & {
-  name: string;
-  type: StringOrLink;
-  accessModifier: string;
-  inherited?: boolean;
-};
-
-export type ClassSource = BaseTypeSource & {
-  __type: 'class';
-  extends?: StringOrLink;
-  implements?: StringOrLink[];
-  constructors?: ConstructorSource[];
-  methods?: MethodSource[];
-  classModifier?: string;
-  sharingModifier?: string;
-  fields?: FieldSource[];
-};
-
-export type InterfaceSource = BaseTypeSource & {
-  __type: 'interface';
-  extends?: StringOrLink[];
-  methods?: MethodSource[];
-};
-
-export type EnumSource = BaseTypeSource & {
-  __type: 'enum';
-  values: EnumValue[];
-};

package/src/transpiler/factory.ts

@@ -1,33 +0,0 @@
-import ProcessorTypeTranspiler from './processor-type-transpiler';
-import { GeneratorChoices } from './generator-choices';
-import { JekyllDocsProcessor } from './markdown/jekyll/jekyll-docsProcessor';
-import DocsifyDocsProcessor from './markdown/docsify/docsify-docs-processor';
-import { PlainMarkdownDocsProcessor } from './markdown/plain-markdown/plain-docsProcessor';
-import { OpenApiDocsProcessor } from './openapi/open-api-docs-processor';
-
-export class TypeTranspilerFactory {
-  private static typeTranspilerCache?: ProcessorTypeTranspiler;
-
-  public static get(generator: GeneratorChoices): ProcessorTypeTranspiler {
-    if (this.typeTranspilerCache) {
-      return this.typeTranspilerCache;
-    }
-
-    switch (generator) {
-      case 'jekyll':
-        this.typeTranspilerCache = new JekyllDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'docsify':
-        this.typeTranspilerCache = new DocsifyDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'plain-markdown':
-        this.typeTranspilerCache = new PlainMarkdownDocsProcessor();
-        return this.typeTranspilerCache;
-      case 'openapi':
-        this.typeTranspilerCache = new OpenApiDocsProcessor();
-        return this.typeTranspilerCache;
-      default:
-        throw Error('Invalid target generator');
-    }
-  }
-}

package/src/transpiler/file-container.ts

@@ -1,13 +0,0 @@
-import { OutputFile } from '../model/outputFile';
-
-export class FileContainer {
-  _files: OutputFile[] = [];
-
-  files(): OutputFile[] {
-    return this._files;
-  }
-
-  pushFile(file: OutputFile): void {
-    this._files.push(file);
-  }
-}

package/src/transpiler/generator-choices.ts

@@ -1 +0,0 @@
-export type GeneratorChoices = 'jekyll' | 'docsify' | 'plain-markdown' | 'openapi';

package/src/transpiler/markdown/class-file-generatorHelper.ts

@@ -1,78 +0,0 @@
-import { Type } from '@cparra/apex-reflection';
-import { TypesRepository } from '../../model/types-repository';
-import { Settings } from '../../settings';
-import State from '../../service/state';
-import { TypeTranspilerFactory } from '../factory';
-import { StringOrLink } from '../../templating/types';
-
-export default class ClassFileGeneratorHelper {
-  public static getSanitizedGroup(classModel: Type) {
-    return this.getClassGroup(classModel).replace(/ /g, '-').replace('.', '');
-  }
-
-  public static getFileLink(classModel: Type) {
-    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(classModel);
-    return `[${fullClassName}](${fileLink})`;
-  }
-
-  private static getFileLinkTuple(classModel: Type): [string, string] {
-    const documentationRoot = Settings.getInstance().getRootDir() ?? '';
-    const directoryRoot = `${documentationRoot}${this.getDirectoryRoot(classModel)}`;
-    const fullClassName = `${Settings.getInstance().getNamespacePrefix()}${classModel.name}`;
-    return [fullClassName, `${directoryRoot}${fullClassName}.md`];
-  }
-
-  public static getFileLinkByTypeName(typeName: string): string {
-    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
-    if (!type) {
-      // If the type is not found, we return a Markdown hyperlink with whatever we received.
-      return `[${typeName}](${typeName})`;
-    }
-
-    return this.getFileLink(type);
-  }
-
-  public static getRenderableLinkByTypeName(typeName: string): StringOrLink {
-    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
-    if (!type) {
-      // If the type is not found, we return the type name as a string.
-      return typeName;
-    }
-
-    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(type);
-    return {
-      title: fullClassName,
-      url: fileLink,
-    };
-  }
-
-  private static getDirectoryRoot(classModel: Type) {
-    // root-relative links start from the root by using a leading '/'
-    const generator = Settings.getInstance().targetGenerator;
-    if (TypeTranspilerFactory.get(generator).getLinkingStrategy() === 'root-relative') {
-      return `/${this.getSanitizedGroup(classModel)}/`;
-    }
-
-    // path-relative links traverse the directory structure
-    const typeBeingProcessed = State.getInstance().getTypeBeingProcessed();
-    if (typeBeingProcessed) {
-      if (this.getClassGroup(typeBeingProcessed) === this.getClassGroup(classModel)) {
-        // If the types the same groups then we simply link directly to that file
-        return './';
-      } else {
-        // If the types have different groups, then we have to go up a directory
-        return `../${this.getSanitizedGroup(classModel)}/`;
-      }
-    } else {
-      // If nothing is being processed, then we assume we are at the root and links should include the groups
-      return `./${this.getSanitizedGroup(classModel)}/`;
-    }
-  }
-
-  private static getClassGroup(classModel: Type): string {
-    const groupAnnotation = classModel.docComment?.annotations.find(
-      (annotation) => annotation.name.toLowerCase() === 'group',
-    );
-    return groupAnnotation?.body ?? Settings.getInstance().getDefaultGroupName();
-  }
-}

package/src/transpiler/markdown/docsify/docsify-docs-processor.ts

@@ -1,12 +0,0 @@
-import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
-import { LinkingStrategy } from '../../processor-type-transpiler';
-
-export default class DocsifyDocsProcessor extends MarkdownTranspilerBase {
-  homeFileName(): string {
-    return 'README';
-  }
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'root-relative';
-  }
-}

package/src/transpiler/markdown/jekyll/jekyll-docsProcessor.ts

@@ -1,50 +0,0 @@
-import { MarkdownTranspilerBase } from '../markdown-transpiler-base';
-import { Type } from '@cparra/apex-reflection';
-import { MarkdownHomeFile } from '../../../model/markdown-home-file';
-import { MarkdownTypeFile } from '../../../model/markdown-type-file';
-import { LinkingStrategy } from '../../processor-type-transpiler';
-import { Settings } from '../../../settings';
-
-export class JekyllDocsProcessor extends MarkdownTranspilerBase {
-  homeFileName(): string {
-    return 'index';
-  }
-
-  onBeforeProcess = (types: Type[]) => {
-    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types, this.frontMatterForHomeFile));
-  };
-
-  onProcess(type: Type): void {
-    this._fileContainer.pushFile(new MarkdownTypeFile(type, 1, this.getFrontMatterHeader(type)));
-  }
-
-  get frontMatterForHomeFile(): string {
-    return '---\nlayout: default\n---';
-  }
-
-  getFrontMatterHeader(type: Type): string {
-    const headerLines = ['---'];
-    // "layout: default" is a required front matter header for Jekyll
-    headerLines.push('layout: default');
-    // Add any additional front matter headers that might have been configured in the settings
-    const targetType = {
-      name: type.name,
-      typeName: type.type_name,
-      accessModifier: type.access_modifier,
-      group: type.group,
-      description: type.docComment?.description,
-    };
-    const configuredHeaders = Settings.getInstance().frontMatterHeader(targetType);
-    if (configuredHeaders) {
-      configuredHeaders.forEach((header) => {
-        headerLines.push(header);
-      });
-    }
-    headerLines.push('---');
-    return headerLines.join('\n');
-  }
-
-  getLinkingStrategy(): LinkingStrategy {
-    return 'path-relative';
-  }
-}

package/src/transpiler/markdown/markdown-transpiler-base.ts

@@ -1,28 +0,0 @@
-import ProcessorTypeTranspiler from '../processor-type-transpiler';
-import { Type } from '@cparra/apex-reflection';
-import { FileContainer } from '../file-container';
-import { MarkdownHomeFile } from '../../model/markdown-home-file';
-import { MarkdownTypeFile } from '../../model/markdown-type-file';
-
-export abstract class MarkdownTranspilerBase extends ProcessorTypeTranspiler {
-  protected readonly _fileContainer: FileContainer;
-
-  constructor() {
-    super();
-    this._fileContainer = new FileContainer();
-  }
-
-  abstract homeFileName(): string;
-
-  fileBuilder(): FileContainer {
-    return this._fileContainer;
-  }
-
-  onBeforeProcess = (types: Type[]) => {
-    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types));
-  };
-
-  onProcess(type: Type): void {
-    this._fileContainer.pushFile(new MarkdownTypeFile(type));
-  }
-}

package/src/transpiler/markdown/plain-markdown/class-template.ts

@@ -1,32 +0,0 @@
-export const classMarkdownTemplate = `
-# {{name}} Class
-{{#if classModifier}}
-\`{{classModifier}}\`
-{{/if}}
-
-{{> typeLevelApexDocPartialTemplate}}
-
-{{#if extends}}
-**Extends**
-{{extends}}
-{{/if}}
-
-{{#if implements}}
-**Implements**
-{{#each implements}}
-{{this}}{{#unless @last}}, {{/unless}}
-{{/each}}
-{{/if}}
-
-{{#if fields}}
-{{> fieldsPartialTemplate}}
-{{/if}}
-
-{{#if constructors}}
-{{> constructorsPartialTemplate}}
-{{/if}}
-
-{{#if methods}}
-{{> methodsPartialTemplate}}
-{{/if}}
-`.trim();

package/src/transpiler/markdown/plain-markdown/constructors-partial-template.ts

@@ -1,35 +0,0 @@
-export const constructorsPartialTemplate = `
-## Constructors
-{{#each constructors}}
-### \`{{title}}\`
-
-{{#> documentablePartialTemplate}}
-
-### Signature
-\`\`\`apex
-{{signature}}
-\`\`\` 
-
-{{#if parameters}}
-### Parameters
-| Name | Type | Description |
-|------|------|-------------|
-{{#each parameters}}
-| {{name}} | {{type}} | {{description}} |
-{{/each}}
-{{/if}}
-
-{{#if throws}}
-### Throws
-{{#each throws}}
-{{this.type}}: {{this.description}}
-
-{{/each}}
-{{/if}}
-
-{{/documentablePartialTemplate}}
-
-{{#unless @last}}---{{/unless}}
-{{/each}}
-
-`.trim();

package/src/transpiler/markdown/plain-markdown/documentable-partial-template.ts

@@ -1,21 +0,0 @@
-export const documentablePartialTemplate = `
-{{#each annotations}}
-\`{{this}}\`
-{{/each}}
-
-{{description}}
-
-{{#each customTags}}
-**{{splitAndCapitalize name}}** {{description}}
-
-{{/each}}
-
-{{> @partial-block}}
-
-{{{mermaid}}}
-
-{{#if example}}
-##{{#if isInner}}#{{/if}} Example
-{{{example}}}
-{{/if}}
-`.trim();

package/src/transpiler/markdown/plain-markdown/enum-template.ts

@@ -1,11 +0,0 @@
-export const enumMarkdownTemplate = `
-# {{name}} Enum
-
-{{> typeLevelApexDocPartialTemplate}}
-
-## Enum Values
-{{#each values}}
-### {{value}}
-{{description}}
-{{/each}}
-`.trim();

package/src/transpiler/markdown/plain-markdown/fieldsPartialTemplate.ts

@@ -1,20 +0,0 @@
-export const fieldsPartialTemplate = `
-## Fields
-{{#each fields}}
-### \`\{{name}}\`
-
-{{#if inherited}}
-*Inherited*
-{{/if}}
-
-{{#> documentablePartialTemplate}}
-
-#### Type
-{{type}}
-
-{{/documentablePartialTemplate}}
-
-{{#unless @last}}---{{/unless}}
-
-{{/each}}
-`.trim();