0
# Docify Command
1

2
> **NOTE**: This is a CLI-only command. @finos/calm-cli does not export functions for programmatic use.
3

4
The `docify` command generates documentation websites from CALM models. It provides a built-in website generator or supports custom templates, transforming CALM architectures into human-readable documentation with navigation, styling, and architecture visualizations.
5

6
## Capabilities
7

8
### Docify Command
9

10
Generate documentation websites from CALM models.
11

12
```typescript { .api }
13
/**
14
 * Generate a documentation website from a CALM model
15
 * @command calm docify [options]
16
 */
17
interface DocifyCommandOptions {
18
  /** Path to CALM architecture JSON file
19
   * CLI flags: -a, --architecture <file>
20
   * Required: yes
21
   */
22
  architecture: string;
23

24
  /** Path to output directory
25
   * CLI flags: -o, --output <file>
26
   * Required: yes
27
   */
28
  output: string;
29

30
  /** Delete output directory contents before processing
31
   * CLI flags: --clear-output-directory
32
   * Default: false
33
   */
34
  clearOutputDirectory?: boolean;
35

36
  /** Path to single .hbs or .md template file
37
   * CLI flags: -t, --template <path>
38
   */
39
  template?: string;
40

41
  /** Path to directory of .hbs/.md templates
42
   * CLI flags: -d, --template-dir <path>
43
   */
44
  templateDir?: string;
45

46
  /** Path to JSON file mapping URLs to local file paths
47
   * CLI flags: -u, --url-to-local-file-mapping <path>
48
   */
49
  urlToLocalFileMapping?: string;
50

51
  /** Enable verbose logging
52
   * CLI flags: -v, --verbose
53
   * Default: false
54
   */
55
  verbose?: boolean;
56
}
57
```
58

59
**Requirements:**
60
- At most one of `template` or `templateDir` can be specified
61
- Cannot use both template options simultaneously
62

63
**Usage Examples:**
64

65
```bash
66
# Generate website using built-in template
67
calm docify -a architecture.json -o ./docs
68

69
# Generate with custom single template
70
calm docify -a architecture.json -o ./docs -t ./custom-template.md
71

72
# Generate with custom template directory
73
calm docify -a architecture.json -o ./docs -d ./custom-templates
74

75
# Clear output directory before generation
76
calm docify -a architecture.json -o ./docs --clear-output-directory
77

78
# With URL-to-local-file mapping
79
calm docify -a architecture.json -o ./docs -u ./url-mappings.json
80

81
# With verbose logging
82
calm docify -a architecture.json -o ./docs -v
83
```
84

85
## Documentation Modes
86

87
### Website Mode (Default)
88

89
When no template is specified, docify uses a built-in template bundle to generate a complete documentation website:
90

91
```bash
92
calm docify -a architecture.json -o ./docs
93
```
94

95
**Generated Website Includes:**
96
- Homepage with architecture overview
97
- Node listings with details
98
- Relationship diagrams
99
- Interface documentation
100
- Navigation menu
101
- Responsive styling
102
- Search functionality (if supported)
103

104
### Custom Template Mode
105

106
Use your own templates for custom documentation formats:
107

108
```bash
109
# Single template
110
calm docify -a architecture.json -o ./docs -t ./template.md
111

112
# Template directory
113
calm docify -a architecture.json -o ./docs -d ./templates
114
```
115

116
## Generated Website Structure
117

118
Using the default website mode:
119

120
```
121
docs/
122
├── index.html           # Homepage with overview
123
├── nodes/
124
│   ├── index.html      # Node listing
125
│   └── [node-id].html  # Individual node pages
126
├── relationships/
127
│   ├── index.html      # Relationship listing
128
│   └── [rel-id].html   # Individual relationship pages
129
├── assets/
130
│   ├── css/
131
│   │   └── styles.css  # Website styling
132
│   └── js/
133
│       └── main.js     # Interactive features
134
└── images/
135
    └── diagrams/       # Generated diagrams
136
```
137

138
## URL-to-Local-File Mapping
139

140
Map external URL references to local files for offline documentation generation:
141

142
### Mapping File Format
143

144
```json
145
{
146
  "https://calm.finos.org/docuflow/flow/document-upload": "flows/flow-document-upload.json",
147
  "https://calm.finos.org/patterns/api-gateway": "patterns/api-gateway.json"
148
}
149
```
150

151
**Usage:**
152

153
```bash
154
calm docify \
155
  -a architecture.json \
156
  -o ./docs \
157
  -u ./url-mappings.json
158
```
159

160
When referenced URLs are encountered in the architecture, content is loaded from local files instead of fetching remotely.
161

162
## Output Behavior
163

164
### Default Behavior
165

166
- Output directory is created if it doesn't exist
167
- Existing files are modified if they match generated output names
168
- Unrelated files remain unchanged
169

170
### Clear Output Directory
171

172
With `--clear-output-directory` flag:
173

174
```bash
175
calm docify -a architecture.json -o ./docs --clear-output-directory
176
```
177

178
**Warning:** Completely deletes all files and subdirectories in the output directory before generation.
179

180
## Template Customization
181

182
### Custom Single Template
183

184
Create a custom Markdown or Handlebars template:
185

186
**custom-docs.md:**
187
```handlebars
188
# {{name}} Architecture
189

190
## Overview
191

192
This architecture contains {{nodes.length}} nodes and {{relationships.length}} relationships.
193

194
## Nodes
195

196
{{#each nodes}}
197
### {{this.name}}
198

199
- **Type:** {{this.node-type}}
200
- **ID:** {{this.unique-id}}
201
{{#if this.description}}
202
- **Description:** {{this.description}}
203
{{/if}}
204

205
{{/each}}
206
```
207

208
**Usage:**
209

210
```bash
211
calm docify -a architecture.json -o ./docs -t ./custom-docs.md
212
```
213

214
### Custom Template Directory
215

216
Create a directory with multiple templates:
217

218
```
219
templates/
220
├── index.md.hbs        # Homepage
221
├── nodes.md.hbs        # Node documentation
222
├── relationships.md.hbs # Relationship documentation
223
└── README.md.hbs       # Additional documentation
224
```
225

226
**Usage:**
227

228
```bash
229
calm docify -a architecture.json -o ./docs -d ./templates
230
```
231

232
Each template generates a corresponding output file.
233

234
## Docify Modes
235

236
The docify command uses different modes from `@finos/calm-shared`:
237

238
### WEBSITE Mode (Default)
239

240
```typescript
241
docifyMode: 'WEBSITE'
242
templateProcessingMode: 'bundle'
243
```
244

245
Uses built-in website template bundle for complete documentation site generation.
246

247
### USER_PROVIDED Mode
248

249
```typescript
250
docifyMode: 'USER_PROVIDED'
251
templateProcessingMode: 'template' | 'template-directory'
252
```
253

254
Uses custom user-provided templates for documentation generation.
255

256
## Common Use Cases
257

258
### Architecture Documentation
259

260
Generate comprehensive architecture documentation:
261

262
```bash
263
calm docify -a architecture.json -o ./docs
264
```
265

266
Share the `./docs` directory via:
267
- Static site hosting (GitHub Pages, Netlify, etc.)
268
- Internal wiki or documentation platform
269
- PDF generation tools
270

271
### API Documentation
272

273
Create API documentation from CALM models with interface details:
274

275
**api-docs.md.hbs:**
276
```handlebars
277
# API Documentation
278

279
{{#each nodes}}
280
{{#if (eq this.node-type "service")}}
281
## {{this.name}} API
282

283
{{#each this.interfaces}}
284
### {{this.protocol}} Interface
285

286
- **Endpoint:** {{this.host}}:{{this.port}}
287
{{#if this.path}}
288
- **Base Path:** {{this.path}}
289
{{/if}}
290

291
{{/each}}
292
{{/if}}
293
{{/each}}
294
```
295

296
### System Diagrams
297

298
Generate documentation with embedded diagrams:
299

300
```handlebars
301
# System Architecture
302

303
## Component Diagram
304

305
```mermaid
306
graph TD
307
{{#each nodes}}
308
  {{this.unique-id}}[{{this.name}}]
309
{{/each}}
310

311
{{#each relationships}}
312
  {{this.relationship-type.connects.source.node}} -->|{{this.relationship-type.type}}| {{this.relationship-type.connects.destination.node}}
313
{{/each}}
314
\```
315
```
316

317
### Deployment Documentation
318

319
Document deployment architecture:
320

321
```handlebars
322
# Deployment Architecture
323

324
{{#each nodes}}
325
## {{this.name}}
326

327
### Deployment Details
328

329
{{#if this.metadata.region}}
330
- **Region:** {{this.metadata.region}}
331
{{/if}}
332
{{#if this.metadata.availability-zone}}
333
- **Availability Zone:** {{this.metadata.availability-zone}}
334
{{/if}}
335

336
### Network Configuration
337

338
{{#each this.interfaces}}
339
- **Protocol:** {{this.protocol}}
340
- **Port:** {{this.port}}
341
{{/each}}
342

343
{{/each}}
344
```
345

346
## Error Handling
347

348
### Common Errors
349

350
**Multiple Template Options:**
351
```
352
❌ Please specify only one of --template or --template-dir
353
```
354
**Solution:** Use at most one template option.
355

356
**Missing Required Options:**
357
```
358
error: required option '-a, --architecture <path>' not specified
359
```
360
**Solution:** Provide required architecture and output options.
361

362
**Architecture File Not Found:**
363
```
364
Error: ENOENT: no such file or directory
365
```
366
**Solution:** Verify architecture file path is correct.
367

368
**Template Not Found:**
369
```
370
Error: Template file not found
371
```
372
**Solution:** Verify template path is correct.
373

374
**Invalid URL Mapping:**
375
```
376
Error reading url to local file mapping file
377
```
378
**Solution:** Verify mapping file is valid JSON.
379

380
## Integration with Other Commands
381

382
Docify is typically used after architecture creation and validation:
383

384
```bash
385
# Step 1: Generate architecture
386
calm generate -p pattern.json -o architecture.json
387

388
# Step 2: Validate architecture
389
calm validate -a architecture.json -p pattern.json
390

391
# Step 3: Generate documentation
392
calm docify -a architecture.json -o ./docs
393

394
# Step 4: Serve documentation locally
395
cd docs
396
python -m http.server 8000
397
# Open http://localhost:8000
398
```
399

400
## Hosting Documentation
401

402
### Static Site Hosting
403

404
#### GitHub Pages
405

406
```bash
407
# Generate docs in docs/ directory
408
calm docify -a architecture.json -o ./docs
409

410
# Commit and push
411
git add docs
412
git commit -m "Update architecture documentation"
413
git push
414

415
# Enable GitHub Pages in repository settings (source: /docs folder)
416
```
417

418
#### Netlify
419

420
```bash
421
# Generate docs
422
calm docify -a architecture.json -o ./docs
423

424
# Deploy to Netlify
425
netlify deploy --dir=docs --prod
426
```
427

428
#### AWS S3
429

430
```bash
431
# Generate docs
432
calm docify -a architecture.json -o ./docs
433

434
# Deploy to S3
435
aws s3 sync ./docs s3://my-architecture-docs --delete
436
```
437

438
### Local Serving
439

440
```bash
441
# Python
442
cd docs && python -m http.server 8000
443

444
# Node.js (with http-server)
445
npx http-server docs -p 8000
446

447
# PHP
448
cd docs && php -S localhost:8000
449
```
450

451
## Advanced Features
452

453
### Embedding External Content
454

455
Reference external flows, patterns, or documentation:
456

457
```json
458
{
459
  "nodes": [{
460
    "unique-id": "service-1",
461
    "flows": ["https://calm.finos.org/flows/authentication.json"]
462
  }]
463
}
464
```
465

466
With URL mapping, these are embedded in the documentation.
467

468
### Multi-Architecture Documentation
469

470
Document multiple related architectures:
471

472
```bash
473
# Generate docs for each architecture
474
calm docify -a prod-architecture.json -o ./docs/prod
475
calm docify -a staging-architecture.json -o ./docs/staging
476
calm docify -a dev-architecture.json -o ./docs/dev
477

478
# Create index page linking to each
479
```
480

481
### Version Control
482

483
Track documentation changes alongside architecture:
484

485
```bash
486
# Generate docs
487
calm docify -a architecture.json -o ./docs
488

489
# Commit architecture and docs together
490
git add architecture.json docs/
491
git commit -m "Update architecture and regenerate docs"
492
```
493

494
### CI/CD Integration
495

496
Automatically regenerate documentation on architecture changes:
497

498
**GitHub Actions Example:**
499

500
```yaml
501
name: Generate Documentation
502
on:
503
  push:
504
    paths:
505
      - 'architecture.json'
506

507
jobs:
508
  generate-docs:
509
    runs-on: ubuntu-latest
510
    steps:
511
      - uses: actions/checkout@v3
512
      - uses: actions/setup-node@v3
513
        with:
514
          node-version: '18'
515
      - run: npm install -g @finos/calm-cli
516
      - run: calm docify -a architecture.json -o ./docs
517
      - run: |
518
          git config user.name github-actions
519
          git config user.email github-actions@github.com
520
          git add docs
521
          git commit -m "Regenerate documentation"
522
          git push
523
```
524

525
## Debugging
526

527
### Verbose Mode
528

529
Enable verbose logging for debugging:
530

531
```bash
532
calm docify -a architecture.json -o ./docs -v
533
```
534

535
Shows:
536
- Template loading
537
- Architecture parsing
538
- File generation
539
- URL mapping resolution
540

541
### Output Inspection
542

543
Review generated files:
544

545
```bash
546
calm docify -a architecture.json -o ./docs
547
ls -la ./docs
548
cat ./docs/index.html
549
```
550

551
### Template Testing
552

553
Test templates with minimal architectures:
554

555
```json
556
{
557
  "$schema": "https://calm.finos.org/schemas/calm-v1.json",
558
  "nodes": [{
559
    "unique-id": "test",
560
    "node-type": "service",
561
    "name": "Test Service"
562
  }]
563
}
564
```
565

566
## Performance Considerations
567

568
### Large Architectures
569

570
For architectures with many nodes:
571
- Use pagination in custom templates
572
- Generate index pages with summaries
573
- Create separate pages for detailed views
574

575
### Asset Generation
576

577
Documentation generation may include:
578
- Diagram generation
579
- Asset copying
580
- CSS/JS bundling
581

582
This can take time for large architectures with many diagrams.
583

584
### Incremental Updates
585

586
Without `--clear-output-directory`, only changed files are regenerated (faster for small updates).
587

588
## Styling and Customization
589

590
### Custom CSS
591

592
When using custom templates, include your own styling:
593

594
```html
595
<!DOCTYPE html>
596
<html>
597
<head>
598
  <link rel="stylesheet" href="custom-styles.css">
599
</head>
600
<body>
601
  <!-- Generated content -->
602
</body>
603
</html>
604
```
605

606
### Themes
607

608
Create reusable template bundles with different themes:
609

610
```
611
themes/
612
├── modern/
613
│   ├── index.json
614
│   ├── templates/
615
│   └── assets/
616
└── classic/
617
    ├── index.json
618
    ├── templates/
619
    └── assets/
620
```
621

622
Use different custom template directories:
623

624
```bash
625
calm docify -a architecture.json -o ./docs-modern -d themes/modern
626
calm docify -a architecture.json -o ./docs-classic -d themes/classic
627
```
628

629
## Best Practices
630

631
1. **Version Documentation:** Commit generated docs alongside architecture files
632
2. **Automate Generation:** Use CI/CD to regenerate docs on architecture changes
633
3. **Use Clear Structure:** Organize documentation with logical navigation
634
4. **Include Examples:** Add usage examples and context to generated docs
635
5. **Test Output:** Review generated documentation before publishing
636
6. **Maintain Templates:** Keep custom templates updated with CALM schema changes
637
7. **Use URL Mappings:** Map external references for offline documentation
638