Skip to content

Add Support for Multiple Source Directories and SFDX Project Integration #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jun 27, 2025
Merged

Add Support for Multiple Source Directories and SFDX Project Integration #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bf0be55
Adding to support for providing multiple source directories or the sf…
cesarParra Jun 26, 2025
3f224a6
Add support for multiple source directories and sfdx-project.json int…
cesarParra Jun 26, 2025
ce451b4
Add support for single source directory in apexdocs build script
cesarParra Jun 26, 2025
77bc4b4
Publishing new version
cesarParra Jun 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .idea/apexdocs.iml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

57 changes: 38 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,12 @@ Run the following command to generate markdown files for your global Salesforce

```bash
apexdocs markdown -s force-app

# Use sfdx-project.json as the source of directories
apexdocs markdown --useSfdxProjectJson

# Specify multiple source directories
apexdocs markdown --sourceDirs force-app force-lwc force-utils
```

#### OpenApi
Expand Down Expand Up @@ -111,21 +117,31 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f

#### 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 |
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | 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 |
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |
| Flag | Alias | Description | Default | Required |
|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
| `--sourceDir` | `-s` | The directory where the source files are located. | N/A | * |
| `--sourceDirs` | N/A | Multiple source directories (space-separated). Cannot be used with `--sourceDir` or `--useSfdxProjectJson`. | N/A | * |
| `--useSfdxProjectJson` | N/A | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir` or `--sourceDirs`. | `false` | * |
| `--sfdxProjectPath` | N/A | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`. | `process.cwd()` | No |
| `--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 |
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | 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 |
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |

> **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
> - `--sourceDir` (single directory)
> - `--sourceDirs` (multiple directories)
> - `--useSfdxProjectJson` (read from sfdx-project.json)
>
> These options are mutually exclusive - you cannot use more than one at the same time.

##### Linking Strategy

Expand Down Expand Up @@ -365,7 +381,8 @@ having to copy-paste the same text across multiple classes, polluting your
source code.

A macro can be defined in your documentation using the `{{macro_name}}` syntax.
In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the macro, and the value is a function that returns the text to inject in place of the macro.
In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
macro, and the value is a function that returns the text to inject in place of the macro.

**Type**

Expand All @@ -379,7 +396,8 @@ type MacroSourceMetadata = {
type MacroFunction = (metadata: MacroSourceMetadata) => string;
```

Notice that the `metadata` object contains information about the source of the file for which the macro is being injected. This allows you to optionally
Notice that the `metadata` object contains information about the source of the file for which the macro is being
injected. This allows you to optionally
return different text based on the source of the file.

Example: Injecting a copyright notice
Expand All @@ -402,13 +420,14 @@ And then in your source code, you can use the macro like this:
* @description This is a class
*/
public class MyClass {
//...
//...
}
```

##### **transformReferenceGuide**

Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether should be skipped.
Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether
should be skipped.

**Type**

Expand Down
101 changes: 101 additions & 0 deletions examples/sfdx-multi-dir/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# ApexDocs SFDX Project Support Example

This example demonstrates the new **sfdx-project.json support** feature in ApexDocs, which allows you to automatically read source directories from your Salesforce project configuration instead of manually specifying them.

## Feature Overview

ApexDocs now supports three ways to specify source directories:

1. **Single Directory** (`--sourceDir`) - The traditional approach
2. **Multiple Directories** (`--sourceDirs`) - Specify multiple directories manually
3. **SFDX Project** (`--useSfdxProjectJson`) - Automatically read from `sfdx-project.json`

## Project Structure

This example project demonstrates a multi-directory Salesforce project structure:

```
sfdx-multi-dir/
├── sfdx-project.json # Project configuration
├── force-app/ # Main application code
│ └── main/default/classes/
│ ├── AccountService.cls
│ └── AccountService.cls-meta.xml
└── force-LWC/ # Lightning Web Component helpers
└── main/default/classes/
├── LWCHelper.cls
└── LWCHelper.cls-meta.xml
```

## Configuration Examples

### Using sfdx-project.json (Recommended)

```bash
# Read directories automatically from sfdx-project.json
apexdocs markdown --useSfdxProjectJson --targetDir ./docs --scope public
```

The `sfdx-project.json` file:
```json
{
"packageDirectories": [
{
"path": "force-app",
"default": true
},
{
"path": "force-LWC",
"default": false
}
]
}
```

### Using Multiple Directories Manually

```bash
# Specify multiple directories manually
apexdocs markdown --sourceDirs force-app force-LWC --targetDir ./docs --scope public
```

### Using Single Directory

```bash
# Traditional single directory approach
apexdocs markdown --sourceDir force-app --targetDir ./docs --scope public
```

### Using SFDX Project with Custom Path

If your `sfdx-project.json` is not in the current directory:

```bash
apexdocs markdown --useSfdxProjectJson --sfdxProjectPath ./my-project --targetDir ./docs
```

### Configuration File Support

You can also use these options in your configuration file:

**package.json:**
```json
{
"apexdocs": {
"useSfdxProjectJson": true,
"scope": ["public", "global"],
"targetDir": "./docs"
}
}
```

**apexdocs.config.js:**
```javascript
module.exports = {
markdown: {
useSfdxProjectJson: true,
scope: ['public', 'global'],
targetDir: './docs'
}
};
```
77 changes: 77 additions & 0 deletions examples/sfdx-multi-dir/docs/account-management/AccountService.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# AccountService Class

Service class for handling Account operations

**Group** Account Management

**Author** ApexDocs Team

## Methods
### `getAccountById(accountId)`

Retrieves an Account record by its Id

#### Signature
```apex
public static Account getAccountById(Id accountId)
```

#### Parameters
| Name | Type | Description |
|------|------|-------------|
| accountId | Id | The Id of the Account to retrieve |

#### Return Type
**Account**

The Account record or null if not found

#### Example
Account acc = AccountService.getAccountById('0011234567890123');

---

### `createAccount(accountName, accountType)`

Creates a new Account record

#### Signature
```apex
public static Id createAccount(String accountName, String accountType)
```

#### Parameters
| Name | Type | Description |
|------|------|-------------|
| accountName | String | The name for the new Account |
| accountType | String | The type of Account to create |

#### Return Type
**Id**

The Id of the newly created Account

#### Throws
DmlException: if the Account cannot be created

---

### `updateAccountIndustry(accountIds, industry)`

Updates the industry field for multiple accounts

#### Signature
```apex
public static Integer updateAccountIndustry(List<Id> accountIds, String industry)
```

#### Parameters
| Name | Type | Description |
|------|------|-------------|
| accountIds | List&lt;Id&gt; | List of Account Ids to update |
| industry | String | The industry value to set |

#### Return Type
**Integer**

Number of successfully updated accounts
13 changes: 13 additions & 0 deletions examples/sfdx-multi-dir/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Reference Guide

## Account Management

### [AccountService](account-management/AccountService.md)

Service class for handling Account operations

## Lightning Web Components

### [LWCHelper](lightning-web-components/LWCHelper.md)

Helper class for Lightning Web Components
Loading