const fs = require('fs'); const path = require('path'); const yaml = require('js-yaml'); // Update docs.json Smartcar Signals & Attributes group with generated group pages function updateDocsJsonWithSignalPages(groupNames) { const docsPath = path.resolve(__dirname, 'docs.json'); const docsRaw = fs.readFileSync(docsPath, 'utf8'); const docs = JSON.parse(docsRaw); // Find the Smartcar Signals & Attributes group let found = false; if (docs.navigation && docs.navigation.tabs) { docs.navigation.tabs.forEach(tab => { if (tab.groups) { tab.groups.forEach(groupObj => { if (groupObj.group === 'Smartcar Signals & Attributes' && Array.isArray(groupObj.pages)) { // Build new page paths const newPages = groupNames.map(name => `api-reference/signals/${name}`); // Remove duplicates, keep only one of each (case-insensitive) const pageSet = new Set(groupObj.pages.map(p => p.toLowerCase())); newPages.forEach(p => pageSet.add(p)); // Always put schema.mdx first if present, then the rest alphabetically const SCHEMA_PATH = 'api-reference/signals/schema'; const allPages = Array.from(pageSet); const schemaIdx = allPages.findIndex(p => p.toLowerCase() === SCHEMA_PATH); let rest = allPages.filter(p => p.toLowerCase() !== SCHEMA_PATH); rest = rest.sort((a, b) => { const aName = a.split('/').pop(); const bName = b.split('/').pop(); return aName.localeCompare(bName); }); const sortedPages = schemaIdx !== -1 ? [SCHEMA_PATH, ...rest] : rest; groupObj.pages = sortedPages; found = true; } }); } }); } if (found) { fs.writeFileSync(docsPath, JSON.stringify(docs, null, 2) + '\n', 'utf8'); console.log('✅ Updated Smartcar Signals & Attributes pages in docs.json'); } else { console.warn('⚠️ Could not find Smartcar Signals & Attributes group in docs.json'); } } // Load and parse YAML file function loadYaml(filePath) { const raw = fs.readFileSync(filePath, 'utf8'); return yaml.load(raw); } // Capitalize first letter function capitalize(str) { if (!str) return ''; return str.charAt(0).toUpperCase() + str.slice(1); } // Generate combined MDX file for both signals and attributes in a group function writeGroupMdxCombined(groupName, signals, attributes, openApi, outputDir) { console.log(`\n🔍 Processing combined group: ${groupName}`); console.log(`📊 Signals in group:`, signals.length); console.log(`📊 Attributes in group:`, attributes.length); signals.forEach((record, index) => { console.log(` Signal ${index + 1}. ${record.name} (${record.signalCode})`); }); attributes.forEach((record, index) => { console.log(` Attribute ${index + 1}. ${record.name} (${record.signalCode})`); }); const lines = []; // Determine title based on what's present let titleSuffix = ''; if (signals.length > 0 && attributes.length > 0) { titleSuffix = 'Signals & Attributes'; } else if (signals.length > 0) { titleSuffix = 'Signals'; } else { titleSuffix = 'Attributes'; } // Metadata lines.push('---'); lines.push(`title: "${groupName} ${titleSuffix}"`); lines.push(`sidebarTitle: "${groupName}"`); lines.push('---\n'); // Helper function to write records of a specific type const writeRecords = (records, typeName) => { if (records.length === 0) return; // Add section header if we have both types if (signals.length > 0 && attributes.length > 0) { lines.push(`## ${typeName}`); lines.push(''); } records.forEach(record => { const displayName = record.displayName || record.name; const signalName = record.name; const signalCode = record.signalCode; const description = record.description; lines.push(`### ${displayName}`); lines.push(''); // Add signal code if available if (signalCode) { lines.push(`Signal code: \`${signalCode}\``); lines.push(''); } // Add description if available if (description) { lines.push(description); lines.push(''); } // Find schema: schemas[GroupName+SignalName] const schemaKey = capitalize(groupName) + capitalize(signalName); const schema = openApi.components?.schemas?.[schemaKey]; if (!schema) { console.log(`Schema not found: ${schemaKey} for group: ${groupName}, signal: ${signalName}`); console.log(`Available schemas starting with ${capitalize(groupName)}:`, Object.keys(openApi.components?.schemas || {}).filter(k => k.startsWith(capitalize(groupName)))); return; } const properties = schema.properties || {}; const required = schema.required || []; // Helper function to generate ParamField for a property const generateParamField = (name, prop, isRequired, indent = ' ', paramType = 'path', isTopLevel = false) => { const type = prop.type || 'object'; const requiredMark = isRequired ? 'true' : 'false'; const lines = []; lines.push(`${indent}`); // For description priority: // 1. Property's own description // 2. For top-level properties: schema description or record description let description = prop.description; if (!description && isTopLevel) { description = schema.description || record.description; } if (description) { lines.push(`${indent} ${description.replace(/\n/g, ' ')}`); } // Add enum values if present if (prop.enum && Array.isArray(prop.enum)) { lines.push(`${indent} `); lines.push(`${indent} **Possible values:** ${prop.enum.map(val => `\`${val}\``).join(', ')}`); } lines.push(`${indent}`); return lines; }; // Helper function to handle nested properties const handleNestedProperties = (properties, required = [], indent = ' ', isTopLevel = true) => { const lines = []; Object.entries(properties).forEach(([propName, prop]) => { if (prop.type === 'array' && prop.items && prop.items.properties) { // Handle array items with nested properties const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); lines.push(`${indent}`); const nestedLines = handleNestedProperties(prop.items.properties, prop.items.required || [], indent + ' ', false); lines.push(...nestedLines); lines.push(`${indent}`); } else if (prop.type === 'object' && prop.properties) { // Handle nested objects const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); lines.push(`${indent}`); const nestedLines = handleNestedProperties(prop.properties, prop.required || [], indent + ' ', false); lines.push(...nestedLines); lines.push(`${indent}`); } else { // Handle basic properties const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); } }); return lines; }; // Generate documentation for all properties const propertyLines = handleNestedProperties(properties, required); lines.push(...propertyLines); // Example if (schema.example) { lines.push(''); lines.push('```json Example'); lines.push(JSON.stringify(schema.example, null, 2)); lines.push('```'); } lines.push(''); }); }; // Write signals first, then attributes writeRecords(signals, 'Signals'); writeRecords(attributes, 'Attributes'); // Write file (always lowercase) const fileName = `${groupName.toLowerCase()}.mdx`; const outPath = path.resolve(outputDir, fileName); if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true }); // Remove any existing file with different casing const filesInDir = fs.readdirSync(outputDir); filesInDir.forEach(f => { if (f.toLowerCase() === fileName && f !== fileName) { try { fs.unlinkSync(path.join(outputDir, f)); console.log(`Removed old file with different case: ${f}`); } catch (err) { console.error(`Error removing file ${f}:`, err); } } }); try { fs.writeFileSync(outPath, lines.join('\n'), 'utf8'); console.log(`✅ Wrote ${outPath}`); if (fs.existsSync(outPath)) { console.log(`File confirmed present: ${outPath}`); } else { console.error(`File missing after write: ${outPath}`); } } catch (err) { console.error(`Error writing file ${outPath}:`, err); } } // Generate per-group MDX files for signals/attributes function writeGroupMdx(groups, type, openApi, outputDir) { Object.keys(groups).forEach(group => { console.log(`\n🔍 Processing ${type} group: ${group}`); console.log(`📊 Records in group:`, groups[group].length); groups[group].forEach((record, index) => { console.log(` ${index + 1}. ${record.name} (${record.signalCode})`); }); const groupRecords = groups[group]; const lines = []; // Metadata const typePlural = capitalize(type) + 's'; lines.push('---'); lines.push(`title: "${group} ${typePlural}"`); lines.push(`sidebarTitle: "${group}"`); lines.push('---\n'); groupRecords.forEach(record => { const displayName = record.displayName || record.name; const signalName = record.name; const signalCode = record.signalCode; const description = record.description; lines.push(`### ${displayName}`); lines.push(''); // Add signal code if available if (signalCode) { lines.push(`Signal code: \`${signalCode}\``); lines.push(''); } // Add description if available if (description) { lines.push(description); lines.push(''); } // Find schema: schemas[GroupName+SignalName] const schemaKey = capitalize(group) + capitalize(signalName); const schema = openApi.components?.schemas?.[schemaKey]; if (!schema) { console.log(`Schema not found: ${schemaKey} for group: ${group}, signal: ${signalName}`); console.log(`Available schemas starting with ${capitalize(group)}:`, Object.keys(openApi.components?.schemas || {}).filter(k => k.startsWith(capitalize(group)))); return; } const properties = schema.properties || {}; const required = schema.required || []; // Helper function to generate ParamField for a property const generateParamField = (name, prop, isRequired, indent = ' ', paramType = 'path', isTopLevel = false) => { const type = prop.type || 'object'; const requiredMark = isRequired ? 'true' : 'false'; const lines = []; lines.push(`${indent}`); // For description priority: // 1. Property's own description // 2. For top-level properties: schema description or record description let description = prop.description; if (!description && isTopLevel) { description = schema.description || record.description; } if (description) { lines.push(`${indent} ${description.replace(/\n/g, ' ')}`); } // Add enum values if present if (prop.enum && Array.isArray(prop.enum)) { lines.push(`${indent} `); lines.push(`${indent} **Possible values:** ${prop.enum.map(val => `\`${val}\``).join(', ')}`); } lines.push(`${indent}`); return lines; }; // Helper function to handle nested properties const handleNestedProperties = (properties, required = [], indent = ' ', isTopLevel = true) => { const lines = []; Object.entries(properties).forEach(([propName, prop]) => { if (prop.type === 'array' && prop.items && prop.items.properties) { // Handle array items with nested properties const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); lines.push(`${indent}`); const nestedLines = handleNestedProperties(prop.items.properties, prop.items.required || [], indent + ' ', false); lines.push(...nestedLines); lines.push(`${indent}`); } else if (prop.type === 'object' && prop.properties) { // Handle nested objects const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); lines.push(`${indent}`); const nestedLines = handleNestedProperties(prop.properties, prop.required || [], indent + ' ', false); lines.push(...nestedLines); lines.push(`${indent}`); } else { // Handle basic properties const paramLines = generateParamField(propName, prop, required.includes(propName), indent, 'path', isTopLevel); lines.push(...paramLines); } }); return lines; }; // Generate documentation for all properties const propertyLines = handleNestedProperties(properties, required); lines.push(...propertyLines); // Example if (schema.example) { lines.push(''); lines.push('```json Example'); lines.push(JSON.stringify(schema.example, null, 2)); lines.push('```'); } lines.push(''); }); // Write file (always lowercase) const fileName = `${group.toLowerCase()}.mdx`; const outPath = path.resolve(outputDir, fileName); if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true }); // Remove any existing file with different casing const filesInDir = fs.readdirSync(outputDir); filesInDir.forEach(f => { if (f.toLowerCase() === fileName && f !== fileName) { try { fs.unlinkSync(path.join(outputDir, f)); console.log(`Removed old file with different case: ${f}`); } catch (err) { console.error(`Error removing file ${f}:`, err); } } }); try { fs.writeFileSync(outPath, lines.join('\n'), 'utf8'); console.log(`✅ Wrote ${outPath}`); if (fs.existsSync(outPath)) { console.log(`File confirmed present: ${outPath}`); } else { console.error(`File missing after write: ${outPath}`); } } catch (err) { console.error(`Error writing file ${outPath}:`, err); } }); } // Load and parse JSON file function loadJson(filePath) { const raw = fs.readFileSync(filePath, 'utf8'); return JSON.parse(raw); } // Filter out deprecated/default and by record type function filterRecords(records, type) { return records.filter(r => r.type === type && !r.isDeprecated && !r.isDefault ); } // Group records by signalGroupId.where.name function groupBySignalGroup(records) { const groups = {}; records.forEach(r => { const groupName = r._links.signalGroupId.where.name; groups[groupName] = groups[groupName] || []; groups[groupName].push(r); }); return groups; } // Write a bullet list of group links to the given file function writeMdx(groups, outputFile) { const lines = []; Object.keys(groups) .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())) .forEach(group => { const groupLink = `/api-reference/signals/${group.toLowerCase()}`; lines.push(`- [${group}](${groupLink})`); }); lines.push(''); const dir = path.dirname(outputFile); if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(outputFile, lines.join('\n'), 'utf8'); } // Main entrypoint function main() { const inputFile = path.resolve(__dirname, 'Signal.json'); const openApiPath = path.resolve(__dirname, 'open-api-merged.yml'); const data = loadJson(inputFile); const openApi = loadYaml(openApiPath); const records = data.records || []; const signals = filterRecords(records, 'signal'); const attrs = filterRecords(records, 'attribute'); const signalGroups = groupBySignalGroup(signals); const attrGroups = groupBySignalGroup(attrs); // Old MDX tables (snippets) writeMdx(signalGroups, path.resolve(__dirname, 'snippets/signals.mdx')); writeMdx(attrGroups, path.resolve(__dirname, 'snippets/attributes.mdx')); // New per-group MDX files for API reference // Merge signals and attributes by group, then write combined files const outputDir = path.resolve(__dirname, 'api-reference/signals'); const allGroups = new Set([...Object.keys(signalGroups), ...Object.keys(attrGroups)]); allGroups.forEach(groupName => { const groupSignals = signalGroups[groupName] || []; const groupAttrs = attrGroups[groupName] || []; writeGroupMdxCombined(groupName, groupSignals, groupAttrs, openApi, outputDir); }); // Collect all group names (signals and attributes), lowercase, deduped const allGroupNames = Array.from(allGroups).map(name => name.toLowerCase()); updateDocsJsonWithSignalPages(allGroupNames); console.log('✅ MDX files generated in /snippets/ and /api-reference/signals/'); } main();

Getting Started

How-To Guides

Tutorials

Dashboard