document configuring

Author: avivkeller

docs/configuration.md

@@ -3,19 +3,16 @@
 `doc-kit`'s CLI supports a `--config-file` option, allowing for custom configuration files to be passed.
 These configuration files must be loadable via a `import()` call, so usually JSON or JavaScript files with default exports.
 
-The structure of these files is the `Configuration` type.
-
 ## Configuration File Format
 
 Configuration files can be either:
 
 - **JavaScript/ESM** (`.mjs`, `.js` with `"type": "module"`)
 - **JSON** (`.json`)
-- **Remote URLs** (loaded dynamically)
 
 ### Basic Example
 
-```javascript name=doc-kit.config.mjs
+```javascript
 export default {
   global: {
     version: '20.0.0',

docs/generators.md

@@ -199,7 +199,7 @@ export default {
    */
   async *generate(input, worker) {
     // Configuration for this generator is based on it's name
-    const { 'parallel-generator': config } = getConfig();
+    const config = getConfig('parallel-generator');
 
     // Prepare serializable dependencies
     const deps = {
@@ -361,7 +361,7 @@ The framework ensures `metadata` runs once and its output is cached for all cons
 ### Writing Output Files
 
 ```javascript
-const { 'my-generator': config } = getConfig();
+const config = getConfig('my-generator');
 
 if (!config.output) {
   // Return data without writing
@@ -389,7 +389,7 @@ return result;
 ### Copying Assets
 
 ```javascript
-const { 'my-generator': config } = getConfig();
+const config = getConfig('my-generator');
 
 if (config.output) {
   // Copy asset directory

src/generators/addon-verify/README.md

@@ -0,0 +1,11 @@
+## `addon-verify` Generator
+
+The `addon-verify` generator extracts code blocks from `doc/api/addons.md` and generates a file list to facilitate C++ compilation and JavaScript runtime validations for Node.js addon examples.
+
+### Configuring
+
+The `addon-verify` generator accepts the following configuration options:
+
+| Name     | Type     | Default | Description                                              |
+| -------- | -------- | ------- | -------------------------------------------------------- |
+| `output` | `string` | -       | The directory where extracted code files will be written |

src/generators/addon-verify/index.mjs

@@ -35,7 +35,7 @@ export default {
    * Generates a file list from code blocks.
    */
   async generate(input) {
-    const { 'addon-verify': config } = getConfig();
+    const config = getConfig('addon-verify');
 
     const sectionsCodeBlocks = input.reduce((addons, node) => {
       const sectionName = node.heading.data.name;

src/generators/api-links/README.md

@@ -0,0 +1,12 @@
+## `api-links` Generator
+
+The `api-links` generator creates a mapping of publicly accessible functions to their source locations in the Node.js repository by analyzing JavaScript source files.
+
+### Configuring
+
+The `api-links` generator accepts the following configuration options:
+
+| Name     | Type      | Default | Description                                         |
+| -------- | --------- | ------- | --------------------------------------------------- |
+| `output` | `string`  | -       | The directory where `apilinks.json` will be written |
+| `minify` | `boolean` | `true`  | Whether to minify the output JSON                   |

src/generators/api-links/index.mjs

@@ -38,7 +38,7 @@ export default {
    * Generates the `apilinks.json` file.
    */
   async generate(input) {
-    const { 'api-links': config } = getConfig();
+    const config = getConfig('api-links');
     /**
      * @type Record<string, string>
      */

src/generators/ast-js/README.md

@@ -0,0 +1,12 @@
+## `ast-js` Generator
+
+The `ast-js` generator parses JavaScript source files into AST (Abstract Syntax Tree) representations using the Acorn parser.
+
+### Configuring
+
+The `ast-js` generator accepts the following configuration options:
+
+| Name     | Type                 | Default | Description                                       |
+| -------- | -------------------- | ------- | ------------------------------------------------- |
+| `input`  | `string \| string[]` | -       | Glob pattern(s) for the JavaScript files to parse |
+| `ignore` | `string \| string[]` | -       | Glob pattern(s) for files to exclude from parsing |

src/generators/ast-js/index.mjs

@@ -53,7 +53,7 @@ export default {
    * Generates a JavaScript AST from the input files.
    */
   async *generate(_, worker) {
-    const { 'ast-js': config } = getConfig();
+    const config = getConfig('ast-js');
 
     const files = globSync(config.input, { ignore: config.ignore }).filter(
       p => extname(p) === '.js'

src/generators/ast/README.md

@@ -0,0 +1,12 @@
+## `ast` Generator
+
+The `ast` generator parses Markdown API documentation files into AST (Abstract Syntax Tree) representations, parallelizing the parsing across worker threads for better performance.
+
+### Configuring
+
+The `ast` generator accepts the following configuration options:
+
+| Name     | Type                 | Default | Description                                       |
+| -------- | -------------------- | ------- | ------------------------------------------------- |
+| `input`  | `string \| string[]` | -       | Glob pattern(s) for the Markdown files to parse   |
+| `ignore` | `string \| string[]` | -       | Glob pattern(s) for files to exclude from parsing |

src/generators/json-simple/README.md

@@ -0,0 +1,12 @@
+## `json-simple` Generator
+
+The `json-simple` generator creates a simplified JSON version of the API documentation, primarily for debugging and testing purposes.
+
+### Configuring
+
+The `json-simple` generator accepts the following configuration options:
+
+| Name     | Type      | Default                 | Description                                         |
+| -------- | --------- | ----------------------- | --------------------------------------------------- |
+| `output` | `string`  | -                       | The directory where `api-docs.json` will be written |
+| `minify` | `boolean` | Inherited from `global` | Whether to minify the output JSON                   |