Skip to content

Commit 3f224a6

Browse files
cesarParracesarParra
committed
Add support for multiple source directories and sfdx-project.json integration
1 parent bf0be55 commit 3f224a6

File tree

28 files changed

+2274
-158
lines changed

28 files changed

+2274
-158
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: 42 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
@@ -101,6 +107,10 @@ Run the following command to generate a changelog for your Salesforce Apex class
101107

102108
```bash
103109
apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir force-app
110+
111+
# NEW: Use sfdx-project.json for both versions
112+
apexdocs changelog --useSfdxProjectJsonForPrevious --sfdxProjectPathForPrevious ./v1.0 \
113+
--useSfdxProjectJsonForCurrent --sfdxProjectPathForCurrent ./v2.0
104114
```
105115

106116
## ▶️ Available Commands
@@ -111,21 +121,31 @@ apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir f
111121

112122
#### Flags
113123

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

@@ -365,7 +385,8 @@ having to copy-paste the same text across multiple classes, polluting your
365385
source code.
366386

367387
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.
388+
In the configuration file, you can then define the macro behavior as a key-value pair, where the key is the name of the
389+
macro, and the value is a function that returns the text to inject in place of the macro.
369390

370391
**Type**
371392

@@ -379,7 +400,8 @@ type MacroSourceMetadata = {
379400
type MacroFunction = (metadata: MacroSourceMetadata) => string;
380401
```
381402

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

385407
Example: Injecting a copyright notice
@@ -402,13 +424,14 @@ And then in your source code, you can use the macro like this:
402424
* @description This is a class
403425
*/
404426
public class MyClass {
405-
//...
427+
//...
406428
}
407429
```
408430

409431
##### **transformReferenceGuide**
410432

411-
Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether should be skipped.
433+
Allows changing the frontmatter and content of the reference guide, or if creating a reference guide page altogether
434+
should be skipped.
412435

413436
**Type**
414437

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

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
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+
```
102+
103+
## Generators Support
104+
105+
All ApexDocs generators support the new multi-directory features:
106+
107+
### Markdown Documentation
108+
```bash
109+
apexdocs markdown --useSfdxProjectJson --targetDir ./docs
110+
```
111+
112+
### OpenAPI Specification
113+
```bash
114+
apexdocs openapi --useSfdxProjectJson --targetDir ./api-docs --fileName api-spec
115+
```
116+
117+
### Changelog Generation
118+
```bash
119+
apexdocs changelog \
120+
--useSfdxProjectJsonForPrevious --sfdxProjectPathForPrevious ./v1.0 \
121+
--useSfdxProjectJsonForCurrent --sfdxProjectPathForCurrent ./v2.0 \
122+
--targetDir ./changelog
123+
```
124+
125+
## Validation and Error Handling
126+
127+
ApexDocs validates your configuration and provides helpful error messages:
128+
129+
### Conflicting Options
130+
```bash
131+
# ❌ This will fail - cannot use both
132+
apexdocs markdown --sourceDir force-app --useSfdxProjectJson
133+
```
134+
135+
### Missing Directories
136+
If directories specified in `sfdx-project.json` don't exist, you'll get a clear error message.
137+
138+
### Empty Configuration
139+
```bash
140+
# ❌ This will fail - must specify at least one source method
141+
apexdocs markdown --targetDir ./docs
142+
```
143+
144+
## Benefits
145+
146+
### 1. **Consistency**
147+
- Uses the same directory structure as your Salesforce project
148+
- No need to maintain separate documentation configuration
149+
150+
### 2. **Automation**
151+
- Automatically includes all package directories
152+
- Works well with CI/CD pipelines
153+
154+
### 3. **Flexibility**
155+
- Mix and match with other configuration options
156+
- Override specific settings when needed
157+
158+
### 4. **Multi-Package Support**
159+
- Perfect for modularized Salesforce projects
160+
- Supports complex project structures
161+
162+
## Migration Guide
163+
164+
### From Single Directory
165+
**Before:**
166+
```bash
167+
apexdocs markdown --sourceDir force-app --targetDir ./docs
168+
```
169+
170+
**After:**
171+
```bash
172+
apexdocs markdown --useSfdxProjectJson --targetDir ./docs
173+
```
174+
175+
### From Configuration Files
176+
**Before (package.json):**
177+
```json
178+
{
179+
"apexdocs": {
180+
"sourceDir": "force-app"
181+
}
182+
}
183+
```
184+
185+
**After (package.json):**
186+
```json
187+
{
188+
"apexdocs": {
189+
"useSfdxProjectJson": true
190+
}
191+
}
192+
```
193+
194+
## Tips and Best Practices
195+
196+
1. **Metadata Files Required**: Ensure all Apex classes have corresponding `.cls-meta.xml` files
197+
2. **Directory Structure**: Follow standard Salesforce project structure (`main/default/classes/`)
198+
3. **Validation**: Use `--scope` parameter to control which classes are documented
199+
4. **Testing**: Test with `--sortAlphabetically` for consistent output
200+
201+
## Running This Example
202+
203+
1. **Install ApexDocs:**
204+
```bash
205+
npm install -g @cparra/apexdocs
206+
```
207+
208+
2. **Generate Documentation:**
209+
```bash
210+
# Using sfdx-project.json
211+
apexdocs markdown --useSfdxProjectJson --targetDir ./docs --scope public --sortAlphabetically
212+
213+
# Using multiple directories manually
214+
apexdocs markdown --sourceDirs force-app force-LWC --targetDir ./docs-manual --scope public
215+
```
216+
217+
3. **View Results:**
218+
```bash
219+
# View the generated documentation
220+
open docs/index.md
221+
```
222+
223+
## Output
224+
225+
The generated documentation will include classes from all specified directories:
226+
227+
- **Account Management** (from force-app)
228+
- AccountService
229+
- **Lightning Web Components** (from force-LWC)
230+
- LWCHelper
231+
232+
This demonstrates how ApexDocs can now seamlessly work with complex, multi-directory Salesforce projects.

0 commit comments

Comments
 (0)