Skip to content

Commit aee7fb4

Browse files
cesarParracesarParra
authored
Merge pull request #262 from cesarParra/sfdx-json-as-source
2 parents 5a79777 + 77bc4b4 commit aee7fb4

30 files changed

+2372
-78
lines changed

‎.idea/apexdocs.iml‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md‎

Lines changed: 38 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,12 @@ Run the following command to generate markdown files for your global Salesforce
8484

8585
```bash
8686
apexdocs markdown -s force-app
87+
88+
# Use sfdx-project.json as the source of directories
89+
apexdocs markdown --useSfdxProjectJson
90+
91+
# Specify multiple source directories
92+
apexdocs markdown --sourceDirs force-app force-lwc force-utils
8793
```
8894

8995
#### OpenApi
@@ -111,21 +117,31 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
111117

112118
#### Flags
113119

114-
| Flag | Alias | Description | Default | Required |
115-
|----------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
116-
| `--sourceDir` | `-s` | The directory where the source files are located. | N/A | Yes |
117-
| `--targetDir` | `-t` | The directory where the generated files will be placed. | `docs` | No |
118-
| `--scope` | `-p` | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. | `[global]` | No |
119-
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | No |
120-
| `--defaultGroupName` | N/A | The default group name to use when a group is not specified. | `Miscellaneous` | No |
121-
| `--namespace` | N/A | The package namespace, if any. If provided, it will be added to the generated files. | N/A | No |
122-
| `--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 |
123-
| `--includeMetadata ` | N/A | Whether to include the file's meta.xml information: Whether it is active and and the API version | `false` | No |
124-
| `--linkingStrategy` | N/A | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none` | `relative` | No |
125-
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
126-
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
127-
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
128-
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |
120+
| Flag | Alias | Description | Default | Required |
121+
|-----------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------|
122+
| `--sourceDir` | `-s` | The directory where the source files are located. | N/A | * |
123+
| `--sourceDirs` | N/A | Multiple source directories (space-separated). Cannot be used with `--sourceDir` or `--useSfdxProjectJson`. | N/A | * |
124+
| `--useSfdxProjectJson` | N/A | Read source directories from `sfdx-project.json` packageDirectories. Cannot be used with `--sourceDir` or `--sourceDirs`. | `false` | * |
125+
| `--sfdxProjectPath` | N/A | Path to directory containing `sfdx-project.json` (defaults to current directory). Only used with `--useSfdxProjectJson`. | `process.cwd()` | No |
126+
| `--targetDir` | `-t` | The directory where the generated files will be placed. | `docs` | No |
127+
| `--scope` | `-p` | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. | `[global]` | No |
128+
| `--customObjectVisibility` | `-v` | Controls which custom objects are documented. Values should be separated by a space. | `[public]` | No |
129+
| `--defaultGroupName` | N/A | The default group name to use when a group is not specified. | `Miscellaneous` | No |
130+
| `--namespace` | N/A | The package namespace, if any. If provided, it will be added to the generated files. | N/A | No |
131+
| `--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 |
132+
| `--includeMetadata ` | N/A | Whether to include the file's meta.xml information: Whether it is active and and the API version | `false` | No |
133+
| `--linkingStrategy` | N/A | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none` | `relative` | No |
134+
| `--customObjectsGroupName` | N/A | The name under which custom objects will be grouped in the Reference Guide | `Custom Objects` | No |
135+
| `--triggersGroupName` | N/A | The name under which triggers will be grouped in the Reference Guide | `Triggers` | No |
136+
| `--includeFieldSecurityMetadata` | N/A | Whether to include the compliance category and security classification for fields in the generated files. | `false` | No |
137+
| `--includeInlineHelpTextMetadata` | N/A | Whether to include the inline help text for fields in the generated files. | `false` | No |
138+
139+
> **Note:** The `*` in the Required column indicates that **one** of the source directory options must be specified:
140+
> - `--sourceDir` (single directory)
141+
> - `--sourceDirs` (multiple directories)
142+
> - `--useSfdxProjectJson` (read from sfdx-project.json)
143+
>
144+
> These options are mutually exclusive - you cannot use more than one at the same time.
129145
130146
##### Linking Strategy
131147

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

367383
A macro can be defined in your documentation using the `{{macro_name}}` syntax.
368-
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.
384+
In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
385+
macro, and the value is a function that returns the text to inject in place of the macro.
369386

370387
**Type**
371388

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

382-
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
399+
Notice that the `metadata` object contains information about the source of the file for which the macro is being
400+
injected. This allows you to optionally
383401
return different text based on the source of the file.
384402

385403
Example: Injecting a copyright notice
@@ -402,13 +420,14 @@ And then in your source code, you can use the macro like this:
402420
* @description This is a class
403421
*/
404422
public class MyClass {
405-
//...
423+
//...
406424
}
407425
```
408426

409427
##### **transformReferenceGuide**
410428

411-
Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether should be skipped.
429+
Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether
430+
should be skipped.
412431

413432
**Type**
414433

‎examples/sfdx-multi-dir/README.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# ApexDocs SFDX Project Support Example
2+
3+
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.
4+
5+
## Feature Overview
6+
7+
ApexDocs now supports three ways to specify source directories:
8+
9+
1. **Single Directory** (`--sourceDir`) - The traditional approach
10+
2. **Multiple Directories** (`--sourceDirs`) - Specify multiple directories manually
11+
3. **SFDX Project** (`--useSfdxProjectJson`) - Automatically read from `sfdx-project.json`
12+
13+
## Project Structure
14+
15+
This example project demonstrates a multi-directory Salesforce project structure:
16+
17+
```
18+
sfdx-multi-dir/
19+
├── sfdx-project.json # Project configuration
20+
├── force-app/ # Main application code
21+
│ └── main/default/classes/
22+
│ ├── AccountService.cls
23+
│ └── AccountService.cls-meta.xml
24+
└── force-LWC/ # Lightning Web Component helpers
25+
└── main/default/classes/
26+
├── LWCHelper.cls
27+
└── LWCHelper.cls-meta.xml
28+
```
29+
30+
## Configuration Examples
31+
32+
### Using sfdx-project.json (Recommended)
33+
34+
```bash
35+
# Read directories automatically from sfdx-project.json
36+
apexdocs markdown --useSfdxProjectJson --targetDir ./docs --scope public
37+
```
38+
39+
The `sfdx-project.json` file:
40+
```json
41+
{
42+
"packageDirectories": [
43+
{
44+
"path": "force-app",
45+
"default": true
46+
},
47+
{
48+
"path": "force-LWC",
49+
"default": false
50+
}
51+
]
52+
}
53+
```
54+
55+
### Using Multiple Directories Manually
56+
57+
```bash
58+
# Specify multiple directories manually
59+
apexdocs markdown --sourceDirs force-app force-LWC --targetDir ./docs --scope public
60+
```
61+
62+
### Using Single Directory
63+
64+
```bash
65+
# Traditional single directory approach
66+
apexdocs markdown --sourceDir force-app --targetDir ./docs --scope public
67+
```
68+
69+
### Using SFDX Project with Custom Path
70+
71+
If your `sfdx-project.json` is not in the current directory:
72+
73+
```bash
74+
apexdocs markdown --useSfdxProjectJson --sfdxProjectPath ./my-project --targetDir ./docs
75+
```
76+
77+
### Configuration File Support
78+
79+
You can also use these options in your configuration file:
80+
81+
**package.json:**
82+
```json
83+
{
84+
"apexdocs": {
85+
"useSfdxProjectJson": true,
86+
"scope": ["public", "global"],
87+
"targetDir": "./docs"
88+
}
89+
}
90+
```
91+
92+
**apexdocs.config.js:**
93+
```javascript
94+
module.exports = {
95+
markdown: {
96+
useSfdxProjectJson: true,
97+
scope: ['public', 'global'],
98+
targetDir: './docs'
99+
}
100+
};
101+
```

‎examples/sfdx-multi-dir/docs/account-management/AccountService.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# AccountService Class
2+
3+
Service class for handling Account operations
4+
5+
**Group** Account Management
6+
7+
**Author** ApexDocs Team
8+
9+
## Methods
10+
### `getAccountById(accountId)`
11+
12+
Retrieves an Account record by its Id
13+
14+
#### Signature
15+
```apex
16+
public static Account getAccountById(Id accountId)
17+
```
18+
19+
#### Parameters
20+
| Name | Type | Description |
21+
|------|------|-------------|
22+
| accountId | Id | The Id of the Account to retrieve |
23+
24+
#### Return Type
25+
**Account**
26+
27+
The Account record or null if not found
28+
29+
#### Example
30+
Account acc = AccountService.getAccountById('0011234567890123');
31+
32+
---
33+
34+
### `createAccount(accountName, accountType)`
35+
36+
Creates a new Account record
37+
38+
#### Signature
39+
```apex
40+
public static Id createAccount(String accountName, String accountType)
41+
```
42+
43+
#### Parameters
44+
| Name | Type | Description |
45+
|------|------|-------------|
46+
| accountName | String | The name for the new Account |
47+
| accountType | String | The type of Account to create |
48+
49+
#### Return Type
50+
**Id**
51+
52+
The Id of the newly created Account
53+
54+
#### Throws
55+
DmlException: if the Account cannot be created
56+
57+
---
58+
59+
### `updateAccountIndustry(accountIds, industry)`
60+
61+
Updates the industry field for multiple accounts
62+
63+
#### Signature
64+
```apex
65+
public static Integer updateAccountIndustry(List<Id> accountIds, String industry)
66+
```
67+
68+
#### Parameters
69+
| Name | Type | Description |
70+
|------|------|-------------|
71+
| accountIds | List&lt;Id&gt; | List of Account Ids to update |
72+
| industry | String | The industry value to set |
73+
74+
#### Return Type
75+
**Integer**
76+
77+
Number of successfully updated accounts

‎examples/sfdx-multi-dir/docs/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Reference Guide
2+
3+
## Account Management
4+
5+
### [AccountService](account-management/AccountService.md)
6+
7+
Service class for handling Account operations
8+
9+
## Lightning Web Components
10+
11+
### [LWCHelper](lightning-web-components/LWCHelper.md)
12+
13+
Helper class for Lightning Web Components

0 commit comments

Comments
 (0)