@cparra/apexdocs 3.3.1 → 3.4.0

package/README.md

@@ -9,10 +9,64 @@
 </div>
 
 ApexDocs is a non-opinionated documentation generator for Salesforce Apex classes.
-It can output documentation in Markdown
-format,
-which allows you to use the Static Site Generator of your choice to create a documentation site that fits your needs,
-hosted in any static web hosting service.
+It can output documentation in Markdown format, which allows you to use the Static Site Generator of your choice to
+create a documentation site that fits your needs, hosted in any static web hosting service.
+
+## 👀 Examples
+
+ApexDocs generates Markdown files, which can be integrated into any Static Site Generation (SSG) engine,
+(e.g. Jekyll, Vitepress, Hugo, Docosaurus, etc.) to create a documentation site that fits your needs.
+
+This gives you the flexibility to create beautiful leveraging your preferred SSG engine, which
+usually provides a wide range of themes, dark mode support, and other features out of the box.
+
+<div align="center">
+  <img src="imgs/vitepress-light.png" alt="Vitepress Light" width="45%" />
+  <img src="imgs/vitepress-dark.png" alt="Vitepress Dark" width="45%" />
+</div>
+
+*These are examples of documentation sites generated using Vitepress.
+Head over to the `examples/vitepress` folder to see the code.*
+
+The extra flexibility also lets you integrate the output documentation with your existing documentation site,
+allowing you to match the look and feel of your existing site.
+
+<div align="center">
+    <img src="imgs/integration.png" alt="Integration" width="70%" />
+</div>
+
+OpenApi REST definitions can be visualized using a tool like ReDoc, Swagger UI, or any other OpenApi viewer.
+
+<div align="center">
+    <img src="imgs/redocly.png" alt="OpenApi" width="70%" />
+</div>
+
+This repo contains several other example implementations in the `examples` directory, showcasing how to integrate
+with different tools.
+
+* [Examples](./examples)
+
+### In the wild
+
+Here are some live projects using ApexDocs:
+
+- [Trailhead Apex Recipes](https://github.com/trailheadapps/apex-recipes)
+- [Salesforce Commerce Apex Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html)
+- [Expression (API)](https://cesarparra.github.io/expression/)
+- [Nimble AMS Docs](https://nimbleuser.github.io/nams-api-docs/#/api-reference/)
+
+## 🚀 Features
+
+* Generate documentation for Salesforce Apex classes as Markdown files
+* Generate an OpenApi REST specification based on `@RestResource` classes
+* Generate a changelog based on the differences between two versions of your Salesforce Apex classes
+* Support for grouping blocks of related code within a class
+* Support for ignoring files and members from being documented
+* Namespace support
+* Configuration file support
+* Single line ApexDoc Blocks
+* Custom tag support
+* And much, much more!
 
 ## 💿 Installation
 
@@ -26,7 +80,7 @@ npm i -g @cparra/apexdocs
 
 #### Markdown
 
-Run the following command to generate markdown files for your global Salesforce Apex classes:
+Run the following command to generate markdown files for your global Salesforce Apex classes and custom objects:
 
 ```bash
 apexdocs markdown -s force-app
@@ -49,38 +103,6 @@ Run the following command to generate a changelog for your Salesforce Apex class
 apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir force-app
 ```
 
-## 🚀 Features
-
-* Generate documentation for Salesforce Apex classes as Markdown files
-* Generate an OpenApi REST specification based on `@RestResource` classes
-* Generate a changelog based on the differences between two versions of your Salesforce Apex classes
-* Support for grouping blocks of related code within a class
-* Support for ignoring files and members from being documented
-* Namespace support
-* Configuration file support
-* Single line ApexDoc Blocks
-* Custom tag support
-* And much, much more!
-
-## 👀 Demo
-
-ApexDocs generates Markdown files, which can be integrated into any Static Site Generation engine,
-(e.g. Jekyll, Vitepress, Hugo, Docosaurus, etc.) to create a documentation site that fits your needs.
-
-This repo contains several example implementations in the `examples` directory, showcasing how to integrate
-with some of these tools.
-
-* [Examples](./examples)
-
-### In the wild
-
-Here are some live projects using ApexDocs:
-
-- [Trailhead Apex Recipes](https://github.com/trailheadapps/apex-recipes)
-- [Salesforce Commerce Apex Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html)
-- [Expression (API)](https://cesarparra.github.io/expression/)
-- [Nimble AMS Docs](https://nimbleuser.github.io/nams-api-docs/#/api-reference/)
-
 ## ▶️ Available Commands
 
 ### Markdown
@@ -89,16 +111,17 @@ Here are some live projects using ApexDocs:
 
 #### Flags
 
-| Flag                   | Alias | Description                                                                                                                                                                                              | Default         | Required |
-|------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
-| `--sourceDir`          | `-s`  | The directory where the source files are located.                                                                                                                                                        | N/A             | Yes      |
-| `--targetDir`          | `-t`  | The directory where the generated files will be placed.                                                                                                                                                  | `docs`          | No       |
-| `--scope`              | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                                                                                      | `global`        | No       |
-| `--defaultGroupName`   | N/A   | The default group name to use when a group is not specified.                                                                                                                                             | `Miscellaneous` | No       |
-| `--namespace`          | N/A   | The package namespace, if any. If provided, it will be added to the generated files.                                                                                                                     | N/A             | No       |
-| `--sortAlphabetically` | N/A   | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false`         | No       |
-| `--includeMetadata `   | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                                                                                         | `false`         | No       |
-| `--linkingStrategy`    | N/A   | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none`                                                                                                 | `relative`      | No       |
+| Flag                      | Alias | Description                                                                                                                                                                                              | Default          | Required |
+|---------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
+| `--sourceDir`             | `-s`  | The directory where the source files are located.                                                                                                                                                        | N/A              | Yes      |
+| `--targetDir`             | `-t`  | The directory where the generated files will be placed.                                                                                                                                                  | `docs`           | No       |
+| `--scope`                 | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                                                                                      | `global`         | No       |
+| `--defaultGroupName`      | N/A   | The default group name to use when a group is not specified.                                                                                                                                             | `Miscellaneous`  | No       |
+| `--namespace`             | N/A   | The package namespace, if any. If provided, it will be added to the generated files.                                                                                                                     | N/A              | No       |
+| `--sortAlphabetically`    | N/A   | Sorts files appearing in the Reference Guide alphabetically, as well as the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false`          | No       |
+| `--includeMetadata `      | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                                                                                         | `false`          | No       |
+| `--linkingStrategy`       | N/A   | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none`                                                                                                 | `relative`       | No       |
+| `--customObjectGroupName` | N/A   | The name under which custom objects will be grouped in the Reference Guide                                                                                                                               | `Custom Objects` | No       |
 
 ##### Linking Strategy
 
@@ -267,12 +290,12 @@ Then you only need to run the top level `apexdocs` command, and it will generate
 Note that you can still run the individual commands if you only want to generate one type of documentation by
 providing the subcommand, e.g `apexdocs markdown` or `apexdocs changelog`.
 
-### Excluding Tags from Appearing in the Documentation
+### Excluding Files from Being Documented
 
-Note: Only works for Markdown documentation.
+Any pattern included in the `.forceignore` file will be excluded from the documentation.
 
-You can exclude tags from appearing in the documentation by using the `excludeTags` property in the configuration file,
-which allow you to pass a list of tags that you want to exclude from the documentation.
+Additionally, you can exclude one or multiple files from being documented by providing a list of glob patterns to
+the `exclude` property in the configuration file.
 
 ```typescript
 import { defineMarkdownConfig } from "@cparra/apexdocs";
@@ -281,15 +304,17 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   targetDir: 'docs',
   scope: ['global', 'public'],
-  excludeTags: ['internal', 'ignore'],
+  exclude: ['**/MyClass.cls', '**/MyOtherClass.cls'],
   ...
 });
 ```
 
-### Excluding Files from Being Documented
+### Excluding Tags from Appearing in the Documentation
 
-You can exclude one or multiple files from being documented by providing a list of glob patterns to
-the `exclude` property in the configuration file.
+Note: Only works for Markdown documentation.
+
+You can exclude tags from appearing in the documentation by using the `excludeTags` property in the configuration file,
+which allow you to pass a list of tags that you want to exclude from the documentation.
 
 ```typescript
 import { defineMarkdownConfig } from "@cparra/apexdocs";
@@ -298,7 +323,7 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   targetDir: 'docs',
   scope: ['global', 'public'],
-  exclude: ['**/MyClass.cls', '**/MyOtherClass.cls'],
+  excludeTags: ['internal', 'ignore'],
   ...
 });
 ```

package/dist/cli/generate.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-var logger$1 = require('../logger-Q5m1eQv2.js');
+var logger$1 = require('../logger-BJXlA0YD.js');
 var module$1 = require('module');
 var cosmiconfig = require('cosmiconfig');
 var E = require('fp-ts/Either');
@@ -17,9 +17,11 @@ require('fp-ts/Option');
 require('fast-xml-parser');
 require('handlebars');
 require('fp-ts/boolean');
+require('fp-ts/Array');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');
+require('@salesforce/source-deploy-retrieve');
 require('chalk');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -73,6 +75,11 @@ const markdownOptions = {
     default: logger$1.markdownDefaults.defaultGroupName,
     describe: "Defines the @group name to be used when a file does not specify it."
   },
+  customObjectGroupName: {
+    type: "string",
+    default: logger$1.markdownDefaults.customObjectsGroupName,
+    describe: "The name under which custom objects will be grouped in the Reference Guide"
+  },
   namespace: {
     type: "string",
     describe: "The package namespace, if any. If provided, it will be added to the generated files."
@@ -285,7 +292,6 @@ function extractArgsForCommandsProvidedInConfig(extractFromProcessFn, config) {
         return _function.pipe(
           extractMultiCommandConfig(extractFromProcessFn, "markdown", generatorConfig),
           E__namespace.map((cliArgs) => {
-            console.log("markdown", cliArgs);
             return cliArgs;
           }),
           E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyMarkdownDefaults), generatorConfig), cliArgs))
@@ -299,7 +305,6 @@ function extractArgsForCommandsProvidedInConfig(extractFromProcessFn, config) {
         return _function.pipe(
           extractMultiCommandConfig(extractFromProcessFn, "changelog", generatorConfig),
           E__namespace.map((cliArgs) => {
-            console.log("changelog", cliArgs);
             return cliArgs;
           }),
           E__namespace.map((cliArgs) => __spreadValues(__spreadValues(__spreadValues({}, configOnlyChangelogDefaults), generatorConfig), cliArgs))
@@ -355,7 +360,6 @@ function extractMultiCommandConfig(extractFromProcessFn, command, config) {
     }
   }
   const options = getOptions(command);
-  console.log("config", config);
   return E__namespace.tryCatch(() => {
     return yargs(extractFromProcessFn()).config(config).options(options).fail((msg) => {
       throw new Error(`Invalid configuration for command "${command}": ${msg}`);

package/dist/index.d.ts

@@ -18,11 +18,13 @@ type UserDefinedMarkdownConfig = {
   scope: string[];
   namespace?: string;
   defaultGroupName: string;
+  customObjectsGroupName: string;
   sortAlphabetically: boolean;
   includeMetadata: boolean;
   linkingStrategy: LinkingStrategy;
   excludeTags: string[];
   referenceGuideTitle: string;
+  /** Glob patterns to exclude files from the documentation. */
   exclude: string[];
 } & Partial<ConfigurableHooks>;
 
@@ -53,7 +55,7 @@ type UserDefinedConfig = UserDefinedMarkdownConfig | UserDefinedOpenApiConfig |
 type SourceFileMetadata = {
   filePath: string;
   name: string;
-  type: 'interface' | 'class' | 'enum';
+  type: 'interface' | 'class' | 'enum' | 'customobject' | 'customfield';
 };
 
 type DocPageReference = {
@@ -84,6 +86,7 @@ type DocPageData = {
   outputDocPath: string;
   frontmatter: Frontmatter;
   content: string;
+  type: 'class' | 'interface' | 'enum' | 'customobject';
 };
 
 /**

package/dist/index.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var logger = require('./logger-Q5m1eQv2.js');
+var logger = require('./logger-BJXlA0YD.js');
 var E = require('fp-ts/Either');
 require('fp-ts/function');
 require('fp-ts/TaskEither');
@@ -13,9 +13,11 @@ require('fp-ts/Option');
 require('fast-xml-parser');
 require('handlebars');
 require('fp-ts/boolean');
+require('fp-ts/Array');
 require('fs');
 require('fp-ts/lib/TaskEither');
 require('minimatch');
+require('@salesforce/source-deploy-retrieve');
 require('chalk');
 
 function _interopNamespaceDefault(e) {