From 1fb55dcb2e0b0fe876f4792669adf9432b535bc6 Mon Sep 17 00:00:00 2001 From: Jacob Richman Date: Fri, 9 Jan 2026 14:28:09 -0800 Subject: [PATCH] Autogenerate docs/cli/settings.md docs/getting-started/configuration.md was already autogenerated but settings.md was not. (#14408) --- docs/cli/settings.md | 121 ++++++++++-------- docs/get-started/configuration.md | 8 +- packages/cli/src/config/settingsSchema.ts | 8 +- .../SettingsDialog.test.tsx.snap | 18 +-- schemas/settings.schema.json | 16 +-- scripts/generate-settings-doc.ts | 105 ++++++++++++--- 6 files changed, 179 insertions(+), 97 deletions(-) diff --git a/docs/cli/settings.md b/docs/cli/settings.md index 3aaeffdf9e..f0df2d48c0 100644 --- a/docs/cli/settings.md +++ b/docs/cli/settings.md @@ -18,45 +18,49 @@ Note: Workspace settings override user settings. Here is a list of all the available settings, grouped by category and ordered as they appear in the UI. + + ### General -| UI Label | Setting | Description | Default | -| ------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- | ----------- | -| Preview Features (e.g., models) | `general.previewFeatures` | Enable preview features (e.g., preview models). | `false` | -| Vim Mode | `general.vimMode` | Enable Vim keybindings. | `false` | -| Disable Auto Update | `general.disableAutoUpdate` | Disable automatic updates. | `false` | -| Enable Prompt Completion | `general.enablePromptCompletion` | Enable AI-powered prompt completion suggestions while typing. | `false` | -| Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` | -| Session Retention | `general.sessionRetention` | Settings for automatic session cleanup. This feature is disabled by default. | `undefined` | -| Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup. | `false` | +| UI Label | Setting | Description | Default | +| ------------------------------- | ---------------------------------- | ------------------------------------------------------------- | ------- | +| Preview Features (e.g., models) | `general.previewFeatures` | Enable preview features (e.g., preview models). | `false` | +| Vim Mode | `general.vimMode` | Enable Vim keybindings | `false` | +| Disable Auto Update | `general.disableAutoUpdate` | Disable automatic updates | `false` | +| Enable Prompt Completion | `general.enablePromptCompletion` | Enable AI-powered prompt completion suggestions while typing. | `false` | +| Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` | +| Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup | `false` | ### Output -| UI Label | Setting | Description | Default | -| ------------- | --------------- | ------------------------------------------------------ | ------- | -| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `text` | +| UI Label | Setting | Description | Default | +| ------------- | --------------- | ------------------------------------------------------ | -------- | +| Output Format | `output.format` | The format of the CLI output. Can be `text` or `json`. | `"text"` | ### UI -| UI Label | Setting | Description | Default | -| ------------------------------ | ---------------------------------------- | -------------------------------------------------------------------- | ------- | -| Hide Window Title | `ui.hideWindowTitle` | Hide the window title bar. | `false` | -| Show Status in Title | `ui.showStatusInTitle` | Show Gemini CLI status and thoughts in the terminal window title. | `false` | -| Hide Tips | `ui.hideTips` | Hide helpful tips in the UI. | `false` | -| Hide Banner | `ui.hideBanner` | Hide the application banner. | `false` | -| Hide Context Summary | `ui.hideContextSummary` | Hide the context summary (GEMINI.md, MCP servers) above the input. | `false` | -| Hide CWD | `ui.footer.hideCWD` | Hide the current working directory path in the footer. | `false` | -| Hide Sandbox Status | `ui.footer.hideSandboxStatus` | Hide the sandbox status indicator in the footer. | `false` | -| Hide Model Info | `ui.footer.hideModelInfo` | Hide the model name and context usage in the footer. | `false` | -| Hide Context Window Percentage | `ui.footer.hideContextPercentage` | Hides the context window remaining percentage. | `true` | -| Hide Footer | `ui.hideFooter` | Hide the footer from the UI. | `false` | -| Show Memory Usage | `ui.showMemoryUsage` | Display memory usage information in the UI. | `false` | -| Show Line Numbers | `ui.showLineNumbers` | Show line numbers in the chat. | `false` | -| Show Citations | `ui.showCitations` | Show citations for generated text in the chat. | `false` | -| Use Full Width | `ui.useFullWidth` | Use the entire width of the terminal for output. | `true` | -| Use Alternate Screen Buffer | `ui.useAlternateBuffer` | Use an alternate screen buffer for the UI, preserving shell history. | `true` | -| Disable Loading Phrases | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility. | `false` | -| Screen Reader Mode | `ui.accessibility.screenReader` | Render output in plain-text to be more screen reader accessible. | `false` | +| UI Label | Setting | Description | Default | +| ------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| Hide Window Title | `ui.hideWindowTitle` | Hide the window title bar | `false` | +| Show Status in Title | `ui.showStatusInTitle` | Show Gemini CLI status and thoughts in the terminal window title | `false` | +| Show Home Directory Warning | `ui.showHomeDirectoryWarning` | Show a warning when running Gemini CLI in the home directory. | `true` | +| Hide Tips | `ui.hideTips` | Hide helpful tips in the UI | `false` | +| Hide Banner | `ui.hideBanner` | Hide the application banner | `false` | +| Hide Context Summary | `ui.hideContextSummary` | Hide the context summary (GEMINI.md, MCP servers) above the input. | `false` | +| Hide CWD | `ui.footer.hideCWD` | Hide the current working directory path in the footer. | `false` | +| Hide Sandbox Status | `ui.footer.hideSandboxStatus` | Hide the sandbox status indicator in the footer. | `false` | +| Hide Model Info | `ui.footer.hideModelInfo` | Hide the model name and context usage in the footer. | `false` | +| Hide Context Window Percentage | `ui.footer.hideContextPercentage` | Hides the context window remaining percentage. | `true` | +| Hide Footer | `ui.hideFooter` | Hide the footer from the UI | `false` | +| Show Memory Usage | `ui.showMemoryUsage` | Display memory usage information in the UI | `false` | +| Show Line Numbers | `ui.showLineNumbers` | Show line numbers in the chat. | `true` | +| Show Citations | `ui.showCitations` | Show citations for generated text in the chat. | `false` | +| Show Model Info In Chat | `ui.showModelInfoInChat` | Show the model name in the chat for each model turn. | `false` | +| Use Full Width | `ui.useFullWidth` | Use the entire width of the terminal for output. | `true` | +| Use Alternate Screen Buffer | `ui.useAlternateBuffer` | Use an alternate screen buffer for the UI, preserving shell history. | `false` | +| Incremental Rendering | `ui.incrementalRendering` | Enable incremental rendering for the UI. This option will reduce flickering but may cause rendering artifacts. Only supported when useAlternateBuffer is enabled. | `true` | +| Disable Loading Phrases | `ui.accessibility.disableLoadingPhrases` | Disable loading phrases for accessibility | `false` | +| Screen Reader Mode | `ui.accessibility.screenReader` | Render output in plain-text to be more screen reader accessible | `false` | ### IDE @@ -69,7 +73,7 @@ they appear in the UI. | UI Label | Setting | Description | Default | | ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------- | ------- | | Max Session Turns | `model.maxSessionTurns` | Maximum number of user/model/tool turns to keep in a session. -1 means unlimited. | `-1` | -| Compression Threshold | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.2` | +| Compression Threshold | `model.compressionThreshold` | The fraction of context usage at which to trigger context compression (e.g. 0.2, 0.3). | `0.5` | | Skip Next Speaker Check | `model.skipNextSpeakerCheck` | Skip the next speaker check. | `true` | ### Context @@ -85,31 +89,40 @@ they appear in the UI. ### Tools -| UI Label | Setting | Description | Default | -| -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------- | -| Enable Interactive Shell | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies. | `true` | -| Show Color | `tools.shell.showColor` | Show color in shell output. | `false` | -| Auto Accept | `tools.autoAccept` | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations). | `false` | -| Use Ripgrep | `tools.useRipgrep` | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` | -| Enable Tool Output Truncation | `tools.enableToolOutputTruncation` | Enable truncation of large tool outputs. | `true` | -| Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold` | Truncate tool output if it is larger than this many characters. Set to -1 to disable. | `10000` | -| Tool Output Truncation Lines | `tools.truncateToolOutputLines` | The number of lines to keep when truncating tool output. | `100` | +| UI Label | Setting | Description | Default | +| -------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | --------- | +| Enable Interactive Shell | `tools.shell.enableInteractiveShell` | Use node-pty for an interactive shell experience. Fallback to child_process still applies. | `true` | +| Show Color | `tools.shell.showColor` | Show color in shell output. | `false` | +| Auto Accept | `tools.autoAccept` | Automatically accept and execute tool calls that are considered safe (e.g., read-only operations). | `false` | +| Use Ripgrep | `tools.useRipgrep` | Use ripgrep for file content search instead of the fallback implementation. Provides faster search performance. | `true` | +| Enable Tool Output Truncation | `tools.enableToolOutputTruncation` | Enable truncation of large tool outputs. | `true` | +| Tool Output Truncation Threshold | `tools.truncateToolOutputThreshold` | Truncate tool output if it is larger than this many characters. Set to -1 to disable. | `4000000` | +| Tool Output Truncation Lines | `tools.truncateToolOutputLines` | The number of lines to keep when truncating tool output. | `1000` | ### Security -| UI Label | Setting | Description | Default | -| ----------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------- | -| Disable YOLO Mode | `security.disableYoloMode` | Disable YOLO mode, even if enabled by a flag. | `false` | -| Blocks extensions from Git | `security.blockGitExtensions` | Blocks installing and loading extensions from Git. | `false` | -| Folder Trust | `security.folderTrust.enabled` | Setting to track whether Folder trust is enabled. | `false` | -| Allowed Environment Variables | `security.environmentVariableRedaction.allowed` | Environment variables to always allow (bypass redaction). | `[]` | -| Blocked Environment Variables | `security.environmentVariableRedaction.blocked` | Environment variables to always redact. | `[]` | +| UI Label | Setting | Description | Default | +| ------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- | ------- | +| Disable YOLO Mode | `security.disableYoloMode` | Disable YOLO mode, even if enabled by a flag. | `false` | +| Allow Permanent Tool Approval | `security.enablePermanentToolApproval` | Enable the "Allow for all future sessions" option in tool confirmation dialogs. | `false` | +| Blocks extensions from Git | `security.blockGitExtensions` | Blocks installing and loading extensions from Git. | `false` | +| Folder Trust | `security.folderTrust.enabled` | Setting to track whether Folder trust is enabled. | `false` | +| Enable Environment Variable Redaction | `security.environmentVariableRedaction.enabled` | Enable redaction of environment variables that may contain secrets. | `false` | ### Experimental -| UI Label | Setting | Description | Default | -| ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | ------- | -| Enable Codebase Investigator | `experimental.codebaseInvestigatorSettings.enabled` | Enable the Codebase Investigator agent. | `true` | -| Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent. | `10` | -| Enable CLI Help Agent | `experimental.cliHelpAgentSettings.enabled` | Enable the CLI Help Agent. | `true` | -| Agent Skills | `experimental.skills` | Enable Agent Skills (experimental). | `false` | +| UI Label | Setting | Description | Default | +| ----------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------- | +| Agent Skills | `experimental.skills` | Enable Agent Skills (experimental). | `false` | +| Enable Codebase Investigator | `experimental.codebaseInvestigatorSettings.enabled` | Enable the Codebase Investigator agent. | `true` | +| Codebase Investigator Max Num Turns | `experimental.codebaseInvestigatorSettings.maxNumTurns` | Maximum number of turns for the Codebase Investigator agent. | `10` | +| Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 sequence for pasting instead of clipboardy (useful for remote sessions). | `false` | +| Enable CLI Help Agent | `experimental.cliHelpAgentSettings.enabled` | Enable the CLI Help Agent. | `true` | + +### Hooks + +| UI Label | Setting | Description | Default | +| ------------------ | --------------------- | ------------------------------------------------ | ------- | +| Hook Notifications | `hooks.notifications` | Show visual indicators when hooks are executing. | `true` | + + diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md index 8d7b95e24d..2ec3edc09b 100644 --- a/docs/get-started/configuration.md +++ b/docs/get-started/configuration.md @@ -159,7 +159,7 @@ their corresponding top-level category object in your `settings.json` file. #### `output` - **`output.format`** (enum): - - **Description:** The format of the CLI output. + - **Description:** The format of the CLI output. Can be `text` or `json`. - **Default:** `"text"` - **Values:** `"text"`, `"json"` @@ -275,7 +275,7 @@ their corresponding top-level category object in your `settings.json` file. #### `ide` - **`ide.enabled`** (boolean): - - **Description:** Enable IDE integration mode + - **Description:** Enable IDE integration mode. - **Default:** `false` - **Requires restart:** Yes @@ -579,12 +579,12 @@ their corresponding top-level category object in your `settings.json` file. - **Default:** `false` - **`context.fileFiltering.respectGitIgnore`** (boolean): - - **Description:** Respect .gitignore files when searching + - **Description:** Respect .gitignore files when searching. - **Default:** `true` - **Requires restart:** Yes - **`context.fileFiltering.respectGeminiIgnore`** (boolean): - - **Description:** Respect .geminiignore files when searching + - **Description:** Respect .geminiignore files when searching. - **Default:** `true` - **Requires restart:** Yes diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts index b69d8f7fe6..7b29ff3d62 100644 --- a/packages/cli/src/config/settingsSchema.ts +++ b/packages/cli/src/config/settingsSchema.ts @@ -323,7 +323,7 @@ const SETTINGS_SCHEMA = { category: 'General', requiresRestart: false, default: 'text', - description: 'The format of the CLI output.', + description: 'The format of the CLI output. Can be `text` or `json`.', showInDialog: true, options: [ { value: 'text', label: 'Text' }, @@ -605,7 +605,7 @@ const SETTINGS_SCHEMA = { category: 'IDE', requiresRestart: true, default: false, - description: 'Enable IDE integration mode', + description: 'Enable IDE integration mode.', showInDialog: true, }, hasSeenNudge: { @@ -854,7 +854,7 @@ const SETTINGS_SCHEMA = { category: 'Context', requiresRestart: true, default: true, - description: 'Respect .gitignore files when searching', + description: 'Respect .gitignore files when searching.', showInDialog: true, }, respectGeminiIgnore: { @@ -863,7 +863,7 @@ const SETTINGS_SCHEMA = { category: 'Context', requiresRestart: true, default: true, - description: 'Respect .geminiignore files when searching', + description: 'Respect .geminiignore files when searching.', showInDialog: true, }, enableRecursiveFileSearch: { diff --git a/packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap b/packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap index 90392e72f1..144b936ab6 100644 --- a/packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap +++ b/packages/cli/src/ui/components/__snapshots__/SettingsDialog.test.tsx.snap @@ -29,7 +29,7 @@ exports[`SettingsDialog > Initial Rendering > should render settings list with v │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -75,7 +75,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'accessibility settings │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -121,7 +121,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'all boolean settings d │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false* │ │ Hide the window title bar │ @@ -167,7 +167,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'default state' correct │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -213,7 +213,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'file filtering setting │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -259,7 +259,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'focused on scope selec │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -305,7 +305,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'mixed boolean and numb │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false* │ │ Hide the window title bar │ @@ -351,7 +351,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'tools and security set │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title false │ │ Hide the window title bar │ @@ -397,7 +397,7 @@ exports[`SettingsDialog > Snapshot Tests > should render 'various boolean settin │ Enable automatic session cleanup │ │ │ │ Output Format Text │ -│ The format of the CLI output. │ +│ The format of the CLI output. Can be \`text\` or \`json\`. │ │ │ │ Hide Window Title true* │ │ Hide the window title bar │ diff --git a/schemas/settings.schema.json b/schemas/settings.schema.json index 2cfbcb5056..33a659a822 100644 --- a/schemas/settings.schema.json +++ b/schemas/settings.schema.json @@ -148,8 +148,8 @@ "properties": { "format": { "title": "Output Format", - "description": "The format of the CLI output.", - "markdownDescription": "The format of the CLI output.\n\n- Category: `General`\n- Requires restart: `no`\n- Default: `text`", + "description": "The format of the CLI output. Can be `text` or `json`.", + "markdownDescription": "The format of the CLI output. Can be `text` or `json`.\n\n- Category: `General`\n- Requires restart: `no`\n- Default: `text`", "default": "text", "type": "string", "enum": ["text", "json"] @@ -362,8 +362,8 @@ "properties": { "enabled": { "title": "IDE Mode", - "description": "Enable IDE integration mode", - "markdownDescription": "Enable IDE integration mode\n\n- Category: `IDE`\n- Requires restart: `yes`\n- Default: `false`", + "description": "Enable IDE integration mode.", + "markdownDescription": "Enable IDE integration mode.\n\n- Category: `IDE`\n- Requires restart: `yes`\n- Default: `false`", "default": false, "type": "boolean" }, @@ -971,15 +971,15 @@ "properties": { "respectGitIgnore": { "title": "Respect .gitignore", - "description": "Respect .gitignore files when searching", - "markdownDescription": "Respect .gitignore files when searching\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", + "description": "Respect .gitignore files when searching.", + "markdownDescription": "Respect .gitignore files when searching.\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", "default": true, "type": "boolean" }, "respectGeminiIgnore": { "title": "Respect .geminiignore", - "description": "Respect .geminiignore files when searching", - "markdownDescription": "Respect .geminiignore files when searching\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", + "description": "Respect .geminiignore files when searching.", + "markdownDescription": "Respect .geminiignore files when searching.\n\n- Category: `Context`\n- Requires restart: `yes`\n- Default: `true`", "default": true, "type": "boolean" }, diff --git a/scripts/generate-settings-doc.ts b/scripts/generate-settings-doc.ts index 6cd5c6a293..1511559705 100644 --- a/scripts/generate-settings-doc.ts +++ b/scripts/generate-settings-doc.ts @@ -30,6 +30,8 @@ const MANUAL_TOP_LEVEL = new Set(['mcpServers', 'telemetry', 'extensions']); interface DocEntry { path: string; type: string; + label: string; + category: string; description: string; defaultValue: string; requiresRestart: boolean; @@ -46,40 +48,61 @@ export async function main(argv = process.argv.slice(2)) { '..', ); const docPath = path.join(repoRoot, 'docs/get-started/configuration.md'); + const cliSettingsDocPath = path.join(repoRoot, 'docs/cli/settings.md'); const { getSettingsSchema } = await loadSettingsSchemaModule(); const schema = getSettingsSchema(); - const sections = collectEntries(schema); - const generatedBlock = renderSections(sections); + const allSettingsSections = collectEntries(schema, { includeAll: true }); + const filteredSettingsSections = collectEntries(schema, { + includeAll: false, + }); - const doc = await readFile(docPath, 'utf8'); + const generatedBlock = renderSections(allSettingsSections); + const generatedTableBlock = renderTableSections(filteredSettingsSections); + + await updateFile(docPath, generatedBlock, checkOnly); + await updateFile(cliSettingsDocPath, generatedTableBlock, checkOnly); +} + +async function updateFile( + filePath: string, + newContent: string, + checkOnly: boolean, +) { + const doc = await readFile(filePath, 'utf8'); const injectedDoc = injectBetweenMarkers({ document: doc, startMarker: START_MARKER, endMarker: END_MARKER, - newContent: generatedBlock, + newContent: newContent, paddingBefore: '\n', paddingAfter: '\n', }); - const formattedDoc = await formatWithPrettier(injectedDoc, docPath); + const formattedDoc = await formatWithPrettier(injectedDoc, filePath); if (normalizeForCompare(doc) === normalizeForCompare(formattedDoc)) { if (!checkOnly) { - console.log('Settings documentation already up to date.'); + console.log( + `Settings documentation (${path.basename(filePath)}) already up to date.`, + ); } return; } if (checkOnly) { console.error( - 'Settings documentation is out of date. Run `npm run docs:settings` to regenerate.', + 'Settings documentation (' + + path.basename(filePath) + + ') is out of date. Run `npm run docs:settings` to regenerate.', ); process.exitCode = 1; return; } - await writeFile(docPath, formattedDoc); - console.log('Settings documentation regenerated.'); + await writeFile(filePath, formattedDoc); + console.log( + `Settings documentation (${path.basename(filePath)}) regenerated.`, + ); } async function loadSettingsSchemaModule() { @@ -87,7 +110,10 @@ async function loadSettingsSchemaModule() { return import(modulePath); } -function collectEntries(schema: SettingsSchemaType) { +function collectEntries( + schema: SettingsSchemaType, + options: { includeAll?: boolean } = {}, +) { const sections = new Map(); const visit = ( @@ -107,7 +133,7 @@ function collectEntries(schema: SettingsSchemaType) { definition.properties && Object.keys(definition.properties).length > 0; - if (!hasChildren) { + if (!hasChildren && (options.includeAll || definition.showInDialog)) { if (!sections.has(sectionKey)) { sections.set(sectionKey, []); } @@ -115,6 +141,8 @@ function collectEntries(schema: SettingsSchemaType) { sections.get(sectionKey)!.push({ path: newPathSegments.join('.'), type: formatType(definition), + label: definition.label, + category: definition.category, description: formatDescription(definition), defaultValue: formatDefaultValue(definition.default, { quoteStrings: true, @@ -162,12 +190,12 @@ function renderSections(sections: Map) { continue; } - lines.push(`#### \`${section}\``); + lines.push('#### `' + section + '`'); lines.push(''); for (const entry of entries) { - lines.push(`- **\`${entry.path}\`** (${entry.type}):`); - lines.push(` - **Description:** ${entry.description}`); + lines.push('- **`' + entry.path + '`** (' + entry.type + '):'); + lines.push(' - **Description:** ' + entry.description); if (entry.defaultValue.includes('\n')) { lines.push(' - **Default:**'); @@ -176,21 +204,21 @@ function renderSections(sections: Map) { lines.push( entry.defaultValue .split('\n') - .map((line) => ` ${line}`) + .map((line) => ' ' + line) .join('\n'), ); lines.push(' ```'); } else { lines.push( - ` - **Default:** \`${escapeBackticks(entry.defaultValue)}\``, + ' - **Default:** `' + escapeBackticks(entry.defaultValue) + '`', ); } if (entry.enumValues && entry.enumValues.length > 0) { const values = entry.enumValues - .map((value) => `\`${escapeBackticks(value)}\``) + .map((value) => '`' + escapeBackticks(value) + '`') .join(', '); - lines.push(` - **Values:** ${values}`); + lines.push(' - **Values:** ' + values); } if (entry.requiresRestart) { @@ -204,6 +232,47 @@ function renderSections(sections: Map) { return lines.join('\n').trimEnd(); } +function renderTableSections(sections: Map) { + const lines: string[] = []; + + for (const [section, entries] of sections) { + if (entries.length === 0) { + continue; + } + + let title = section.charAt(0).toUpperCase() + section.slice(1); + if (title === 'Ui') { + title = 'UI'; + } else if (title === 'Ide') { + title = 'IDE'; + } + lines.push(`### ${title}`); + lines.push(''); + lines.push('| UI Label | Setting | Description | Default |'); + lines.push('| --- | --- | --- | --- |'); + + for (const entry of entries) { + const val = entry.defaultValue.replace(/\n/g, ' '); + const defaultVal = '`' + escapeBackticks(val) + '`'; + lines.push( + '| ' + + entry.label + + ' | `' + + entry.path + + '` | ' + + entry.description + + ' | ' + + defaultVal + + ' |', + ); + } + + lines.push(''); + } + + return lines.join('\n').trimEnd(); +} + if (process.argv[1]) { const entryUrl = pathToFileURL(path.resolve(process.argv[1])).href; if (entryUrl === import.meta.url) {