@cparra/apexdocs 2.25.0-alpha.9 → 3.0.0-alpha.1

package/dist/cli/generate.js

@@ -5,13 +5,13 @@ var _function = require('fp-ts/function');
 var E = require('fp-ts/Either');
 var TE = require('fp-ts/TaskEither');
 var yaml = require('js-yaml');
+var path = require('path');
 var apexReflection = require('@cparra/apex-reflection');
 var O = require('fp-ts/Option');
 var fastXmlParser = require('fast-xml-parser');
 var Handlebars = require('handlebars');
-var defaults = require('../defaults-DUwru49Q.js');
+var defaults = require('../defaults-jLXD2y8-.js');
 var fs = require('fs');
-var path = require('path');
 var chalk = require('chalk');
 var logUpdate = require('log-update');
 var cosmiconfig = require('cosmiconfig');
@@ -38,9 +38,9 @@ function _interopNamespaceDefault(e) {
 var E__namespace = /*#__PURE__*/_interopNamespaceDefault(E);
 var TE__namespace = /*#__PURE__*/_interopNamespaceDefault(TE);
 var yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var O__namespace = /*#__PURE__*/_interopNamespaceDefault(O);
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
-var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 var yargs__namespace = /*#__PURE__*/_interopNamespaceDefault(yargs);
 
 function apply(fn, ...front) {
@@ -570,7 +570,7 @@ function singleGroup(headingLevel, groupName, adapter, members, linkGenerator) {
 }
 
 function parsedFilesToRenderableBundle(config, parsedFiles, references) {
-  const referenceFinder = apply(linkGenerator, references);
+  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
   function toReferenceGuide(parsedFiles2) {
     return parsedFiles2.reduce(
       addToReferenceGuide(referenceFinder, config, references),
@@ -604,11 +604,15 @@ function addToReferenceGuide(findLinkFromHome, config, references) {
     return acc;
   };
 }
-const linkGenerator = (references, referenceName) => {
+const linkGenerator = (references, documentationRootDir, referenceName) => {
   const reference = references[referenceName];
   return reference ? (
     // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
-    { __type: "link", title: reference.displayName, url: `/${reference.pathFromRoot}` }
+    {
+      __type: "link",
+      title: reference.displayName,
+      url: path__namespace.join("/", documentationRootDir, reference.pathFromRoot)
+    }
   ) : referenceName;
 };
 function getTypeGroup$1(type, config) {
@@ -2859,27 +2863,17 @@ const markdownOptions = {
     array: true,
     alias: "p",
     default: defaults.defaults.scope,
-    describe: "A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource."
+    describe: "A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled."
   },
   defaultGroupName: {
     type: "string",
     default: defaults.defaults.defaultGroupName,
     describe: "Defines the @group name to be used when a file does not specify it."
   },
-  openApiTitle: {
-    type: "string",
-    default: "Apex REST Api",
-    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.'
-  },
   namespace: {
     type: "string",
     describe: "The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. If generating an OpenApi definition, it will be added to the file's Server Url."
   },
-  openApiFileName: {
-    type: "string",
-    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-    default: "openapi"
-  },
   sortMembersAlphabetically: {
     type: "boolean",
     describe: "Whether to sort members alphabetically.",
@@ -2889,6 +2883,11 @@ const markdownOptions = {
     type: "boolean",
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.defaults.includeMetadata
+  },
+  documentationRootDir: {
+    type: "string",
+    describe: "The root directory of the documentation. This is used to generate the correct relative paths.",
+    default: defaults.defaults.documentationRootDir
   }
 };
 
@@ -2955,10 +2954,10 @@ function extractArgs() {
 }
 
 function main() {
-  function cathError(error) {
+  function catchError(error) {
     console.error(error);
     process.exit(1);
   }
-  extractArgs().then((config) => Apexdocs.generate(config).catch(cathError)).catch(cathError);
+  extractArgs().then((config) => Apexdocs.generate(config).catch(catchError)).catch(catchError);
 }
 main();

package/dist/defaults-jLXD2y8-.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const defaults = {
+  targetGenerator: "markdown",
+  targetDir: "./docs/",
+  scope: ["global"],
+  defaultGroupName: "Miscellaneous",
+  includeMetadata: false,
+  sortMembersAlphabetically: false,
+  documentationRootDir: ""
+};
+
+exports.defaults = defaults;

package/dist/index.d.ts

@@ -19,6 +19,7 @@ type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
+  documentationRootDir: string;
 } & Partial<ConfigurableHooks>;
 
 type SourceFileMetadata = {
@@ -93,7 +94,7 @@ type TransformDocPage = (
   doc: DocPageData,
 ) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>;
 
-type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'>, 'targetGenerator'>;
+type ConfigurableMarkdownConfig = Omit<SetOptional<UserDefinedMarkdownConfig, 'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'documentationRootDir'>, 'targetGenerator'>;
 declare function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig;
 declare function skip(): Skip;
 

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var defaults = require('./defaults-DUwru49Q.js');
+var defaults = require('./defaults-jLXD2y8-.js');
 
 var __defProp = Object.defineProperty;
 var __defProps = Object.defineProperties;

package/package.json

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

package/src/cli/args.ts

@@ -26,7 +26,7 @@ function _extractYargs(config?: CosmiconfigResult) {
     .command('markdown', 'Generate documentation from Apex classes as a Markdown site.', (yargs) =>
       yargs.options(markdownOptions),
     )
-    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.')
+    .command('openapi', 'Generate an OpenApi REST specification from Apex classes.') // TODO: Add OpenApi specific options
     .demandCommand()
     .parseSync();
 }

package/src/cli/commands/markdown.ts

@@ -21,30 +21,19 @@ export const markdownOptions: { [key: string]: Options } = {
     default: defaults.scope,
     describe:
       'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
-      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled. ' +
-      'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
+      'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
   },
   defaultGroupName: {
     type: 'string',
     default: defaults.defaultGroupName,
     describe: 'Defines the @group name to be used when a file does not specify it.',
   },
-  openApiTitle: {
-    type: 'string',
-    default: 'Apex REST Api',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
-  },
   namespace: {
     type: 'string',
     describe:
       'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
       "If generating an OpenApi definition, it will be added to the file's Server Url.",
   },
-  openApiFileName: {
-    type: 'string',
-    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
-    default: 'openapi',
-  },
   sortMembersAlphabetically: {
     type: 'boolean',
     describe: 'Whether to sort members alphabetically.',
@@ -55,4 +44,9 @@ export const markdownOptions: { [key: string]: Options } = {
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
     default: defaults.includeMetadata,
   },
+  documentationRootDir: {
+    type: 'string',
+    describe: 'The root directory of the documentation. This is used to generate the correct relative paths.',
+    default: defaults.documentationRootDir,
+  },
 };

package/src/cli/generate.ts

@@ -3,14 +3,14 @@ import { Apexdocs } from '../application/Apexdocs';
 import { extractArgs } from './args';
 
 function main() {
-  function cathError(error: Error) {
+  function catchError(error: Error) {
     console.error(error);
     process.exit(1);
   }
 
   extractArgs()
-    .then((config) => Apexdocs.generate(config).catch(cathError))
-    .catch(cathError);
+    .then((config) => Apexdocs.generate(config).catch(catchError))
+    .catch(catchError);
 }
 
 main();

package/src/core/markdown/__test__/test-helpers.ts

@@ -18,5 +18,6 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     sortMembersAlphabetically: true,
     referenceGuideTemplate: referenceGuideTemplate,
     ...config,
+    documentationRootDir: '',
   });
 }

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

@@ -15,6 +15,7 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
   sortMembersAlphabetically: false,
+  documentationRootDir: '',
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

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

@@ -5,13 +5,14 @@ import { adaptDescribable } from './documentables';
 import { MarkdownGeneratorConfig } from '../generate-docs';
 import { apply } from '#utils/fp';
 import { Type } from '@cparra/apex-reflection';
+import * as path from 'path';
 
 export function parsedFilesToRenderableBundle(
   config: MarkdownGeneratorConfig,
   parsedFiles: ParsedFile[],
   references: Record<string, DocPageReference>,
 ): RenderableBundle {
-  const referenceFinder = apply(linkGenerator, references);
+  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
 
   function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
     return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
@@ -54,11 +55,20 @@ function addToReferenceGuide(
   };
 }
 
-const linkGenerator = (references: Record<string, DocPageReference>, referenceName: string): StringOrLink => {
+const linkGenerator = (
+  references: Record<string, DocPageReference>,
+  documentationRootDir: string,
+  referenceName: string,
+): StringOrLink => {
   const reference: DocPageReference | undefined = references[referenceName];
+
   return reference
     ? // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
-      { __type: 'link', title: reference.displayName, url: `/${reference.pathFromRoot}` }
+      {
+        __type: 'link',
+        title: reference.displayName,
+        url: path.join('/', documentationRootDir, reference.pathFromRoot),
+      }
     : referenceName;
 };
 

package/src/core/markdown/generate-docs.ts

@@ -42,6 +42,7 @@ export type MarkdownGeneratorConfig = Pick<
   | 'transformDocs'
   | 'transformDocPage'
   | 'transformReference'
+  | 'documentationRootDir'
 > & {
   referenceGuideTemplate: string;
   sortMembersAlphabetically: boolean;

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

@@ -21,6 +21,7 @@ export type UserDefinedMarkdownConfig = {
   namespace?: string;
   sortMembersAlphabetically: boolean;
   includeMetadata: boolean;
+  documentationRootDir: string;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {

package/src/defaults.ts

@@ -5,4 +5,5 @@ export const defaults = {
   defaultGroupName: 'Miscellaneous',
   includeMetadata: false,
   sortMembersAlphabetically: false,
+  documentationRootDir: '',
 };

package/src/index.ts

@@ -12,7 +12,12 @@ import { defaults } from './defaults';
 type ConfigurableMarkdownConfig = Omit<
   SetOptional<
     UserDefinedMarkdownConfig,
-    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically'
+    | 'targetDir'
+    | 'scope'
+    | 'defaultGroupName'
+    | 'includeMetadata'
+    | 'sortMembersAlphabetically'
+    | 'documentationRootDir'
   >,
   'targetGenerator'
 >;