Skip to content

Commit 471bea6

Browse files
avivkelleravivkeller
authored
feat(cli): add a configuration file option (#593)
1 parent f8758bf commit 471bea6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

88 files changed

+1730
-918
lines changed

‎bin/commands/generate.mjs‎

Lines changed: 36 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,40 @@
1-
import { cpus } from 'node:os';
2-
31
import { Command, Option } from 'commander';
4-
import { coerce } from 'semver';
52

6-
import { NODE_CHANGELOG_URL, NODE_VERSION } from '../../src/constants.mjs';
73
import { publicGenerators } from '../../src/generators/index.mjs';
84
import createGenerator from '../../src/generators.mjs';
9-
import logger from '../../src/logger/index.mjs';
10-
import { parseTypeMap } from '../../src/parsers/json.mjs';
11-
import { parseChangelog, parseIndex } from '../../src/parsers/markdown.mjs';
12-
import { DEFAULT_TYPE_MAP } from '../../src/utils/parser/constants.mjs';
5+
import { setConfig } from '../../src/utils/configuration/index.mjs';
136
import { errorWrap } from '../utils.mjs';
147

8+
const { runGenerators } = createGenerator();
9+
10+
/**
11+
* @typedef {Object} CLIOptions
12+
* @property {string[]} input
13+
* @property {string[]} target
14+
* @property {string[]} ignore
15+
* @property {string} output
16+
* @property {number} threads
17+
* @property {number} chunkSize
18+
* @property {string} version
19+
* @property {string} changelog
20+
* @property {string} gitRef
21+
* @property {string} index
22+
* @property {boolean} minify
23+
* @property {string} typeMap
24+
*/
25+
1526
export default new Command('generate')
1627
.description('Generate API docs')
28+
.addOption(new Option('--config-file <path>', 'Config file'))
29+
30+
// Options that need to be converted into a configuration
1731
.addOption(
18-
new Option(
19-
'-i, --input <patterns...>',
20-
'Input file patterns (glob)'
21-
).makeOptionMandatory()
32+
new Option('-i, --input <patterns...>', 'Input file patterns (glob)')
33+
)
34+
.addOption(
35+
new Option('-t, --target <generator...>', 'Target generator(s)').choices(
36+
Object.keys(publicGenerators)
37+
)
2238
)
2339
.addOption(
2440
new Option('--ignore <patterns...>', 'Ignore file patterns (glob)')
@@ -29,63 +45,23 @@ export default new Command('generate')
2945
'-p, --threads <number>',
3046
'Number of threads to use (minimum: 1)'
3147
)
32-
.default(cpus().length)
33-
.argParser(parseInt)
3448
)
3549
.addOption(
3650
new Option(
3751
'--chunk-size <number>',
3852
'Number of items to process per worker thread (minimum: 1)'
3953
)
40-
.default(10)
41-
.argParser(parseInt)
42-
)
43-
.addOption(
44-
new Option('-v, --version <semver>', 'Target Node.js version').default(
45-
NODE_VERSION
46-
)
47-
)
48-
.addOption(
49-
new Option('-c, --changelog <url>', 'Changelog URL or path').default(
50-
NODE_CHANGELOG_URL
51-
)
52-
)
53-
.addOption(
54-
new Option('--git-ref', 'Git ref URL').default(
55-
'https://github.com/nodejs/node/tree/HEAD'
56-
)
57-
)
58-
.addOption(
59-
new Option('-t, --target <generator...>', 'Target generator(s)')
60-
.makeOptionMandatory()
61-
.choices(Object.keys(publicGenerators))
6254
)
55+
.addOption(new Option('-v, --version <semver>', 'Target Node.js version'))
56+
.addOption(new Option('-c, --changelog <url>', 'Changelog URL or path'))
57+
.addOption(new Option('--git-ref', 'Git ref URL'))
6358
.addOption(new Option('--index <url>', 'index.md URL or path'))
64-
.addOption(
65-
new Option('--type-map <url>', 'Type map URL or path').default(
66-
DEFAULT_TYPE_MAP
67-
)
68-
)
59+
.addOption(new Option('--minify', 'Minify?'))
60+
.addOption(new Option('--type-map <url>', 'Type map URL or path'))
61+
6962
.action(
7063
errorWrap(async opts => {
71-
logger.debug('Starting doc-kit', opts);
72-
73-
const { runGenerators } = createGenerator();
74-
75-
logger.debug('Starting generation', { targets: opts.target });
76-
77-
await runGenerators({
78-
generators: opts.target,
79-
input: opts.input,
80-
ignore: opts.ignore,
81-
output: opts.output,
82-
version: coerce(opts.version),
83-
releases: await parseChangelog(opts.changelog),
84-
gitRef: opts.gitRef,
85-
threads: Math.max(opts.threads, 1),
86-
chunkSize: Math.max(opts.chunkSize, 1),
87-
index: await parseIndex(opts.index),
88-
typeMap: await parseTypeMap(opts.typeMap),
89-
});
64+
const config = await setConfig(opts);
65+
await runGenerators(config);
9066
})
9167
);

‎docs/configuration.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Configuration
2+
3+
`doc-kit`'s CLI supports a `--config-file` option, allowing for custom configuration files to be passed.
4+
These configuration files must be loadable via a `import()` call, so usually JSON or JavaScript files with default exports.
5+
6+
## Configuration File Format
7+
8+
Configuration files can be either:
9+
10+
- **JavaScript/ESM** (`.mjs`, `.js` with `"type": "module"`)
11+
- **JSON** (`.json`)
12+
13+
### Basic Example
14+
15+
```javascript
16+
export default {
17+
global: {
18+
version: '20.0.0',
19+
minify: true,
20+
repository: 'nodejs/node',
21+
ref: 'main',
22+
baseURL: 'https://nodejs.org/docs/',
23+
input: 'src/',
24+
output: 'dist/',
25+
ignore: ['node_modules/', 'test/'],
26+
changelog:
27+
'https://raw.githubusercontent.com/nodejs/node/main/CHANGELOG.md',
28+
index:
29+
'https://raw.githubusercontent.com/nodejs/node/main/doc/api/index.md',
30+
},
31+
32+
threads: 4,
33+
chunkSize: 10,
34+
35+
// Generator-specific configurations
36+
json: {
37+
format: 'json',
38+
minify: false, // Override global setting
39+
},
40+
41+
html: {
42+
format: 'html',
43+
},
44+
45+
metadata: {
46+
typeMap: {
47+
String: 'string',
48+
Number: 'number',
49+
Boolean: 'boolean',
50+
},
51+
},
52+
};
53+
```
54+
55+
## Configuration Structure
56+
57+
### Global Configuration
58+
59+
The `global` object contains settings that apply to all generators unless overridden:
60+
61+
| Property | Type | Description | Default |
62+
| ------------ | ------------------ | ------------------------------------------ | -------------------------------------------------- |
63+
| `version` | `string \| SemVer` | Documentation version | `process.version` |
64+
| `minify` | `boolean` | Whether to minify output | `true` |
65+
| `repository` | `string` | GitHub repository in `owner/repo` format | `'nodejs/node'` |
66+
| `ref` | `string` | Git reference (branch, tag, or commit SHA) | `'HEAD'` |
67+
| `baseURL` | `string \| URL` | Base URL for documentation | `'https://nodejs.org/docs'` |
68+
| `input` | `string[]` | Input directory path | - |
69+
| `output` | `string` | Output directory path | - |
70+
| `ignore` | `string[]` | Patterns to ignore | `[]` |
71+
| `changelog` | `string \| URL` | Changelog URL | Auto-generated URL based on `ref` and `repository` |
72+
| `index` | `string \| URL` | Index URL | - |
73+
74+
### Generator-Specific Configuration
75+
76+
Each generator (e.g., `json`, `html`, `markdown`) can have its own configuration that overrides global settings:
77+
78+
```javascript
79+
export default {
80+
global: {
81+
version: '20.0.0',
82+
minify: true,
83+
},
84+
85+
'legacy-json': {
86+
minify: false, // Override: JSON output won't be minified
87+
},
88+
};
89+
```
90+
91+
## Configuration Merging
92+
93+
Configurations are merged in the following order (earlier sources take precedence):
94+
95+
1. **Config file** (`--config-file`)
96+
2. **CLI options** (command-line arguments)
97+
3. **Default values** (built-in defaults)
98+
99+
## CLI Options Mapping
100+
101+
CLI options map to configuration properties:
102+
103+
| CLI Option | Config Property | Example |
104+
| ---------------------- | ------------------ | ------------------------- |
105+
| `--input <path>` | `global.input` | `--input src/` |
106+
| `--output <path>` | `global.output` | `--output dist/` |
107+
| `--ignore <pattern>` | `global.ignore[]` | `--ignore test/` |
108+
| `--minify` | `global.minify` | `--minify` |
109+
| `--git-ref <ref>` | `global.ref` | `--git-ref v20.0.0` |
110+
| `--version <version>` | `global.version` | `--version 20.0.0` |
111+
| `--changelog <url>` | `global.changelog` | `--changelog https://...` |
112+
| `--index <url>` | `global.index` | `--index file://...` |
113+
| `--type-map <map>` | `metadata.typeMap` | `--type-map file://...` |
114+
| `--target <generator>` | `target` | `--target json` |
115+
| `--threads <n>` | `threads` | `--threads 4` |
116+
| `--chunk-size <n>` | `chunkSize` | `--chunk-size 10` |

0 commit comments

Comments
 (0)