'use strict'; /** * build-signal-mdx.js * * Generates per-group MDX files for the Smartcar Signals & Attributes section, * sourced from specs/vehicle-signals.yml (built by build-vehicle-signals-spec.js). * * Outputs: * api-reference/signals/.mdx — one page per signal group * snippets/signals.mdx — bullet list of group links * docs.json — nav updated with generated pages * * Run with: node scripts/build-signal-mdx.js */ const fs = require('fs'); const path = require('path'); const yaml = require('js-yaml'); const VEHICLE_SIGNALS_PATH = path.resolve(__dirname, '../specs/vehicle-signals.yml'); const OUTPUT_DIR = path.resolve(__dirname, '../api-reference/signals'); const SNIPPETS_DIR = path.resolve(__dirname, '../snippets'); const DOCS_JSON_PATH = path.resolve(__dirname, '../docs.json'); const SCHEMA_NAV_PATH = 'api-reference/signals/schema'; // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- function loadYaml(filePath) { return yaml.load(fs.readFileSync(filePath, 'utf8')); } function generateParamField(name, prop, isRequired, indent = ' ') { const type = prop.type || 'object'; const lines = []; lines.push(`${indent}`); if (prop.description) { lines.push(`${indent} ${prop.description.replace(/\n/g, ' ')}`); } if (prop.enum && Array.isArray(prop.enum)) { lines.push(`${indent} `); lines.push(`${indent} **Possible values:** ${prop.enum.map(v => `\`${v}\``).join(', ')}`); } lines.push(`${indent}`); return lines; } function handleNestedProperties(properties, required = [], indent = ' ') { const lines = []; Object.entries(properties).forEach(([propName, prop]) => { if (prop.type === 'array' && prop.items && prop.items.properties) { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); lines.push(`${indent}`); lines.push(...handleNestedProperties(prop.items.properties, prop.items.required || [], indent + ' ')); lines.push(`${indent}`); } else if (prop.type === 'object' && prop.properties) { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); lines.push(`${indent}`); lines.push(...handleNestedProperties(prop.properties, prop.required || [], indent + ' ')); lines.push(`${indent}`); } else { lines.push(...generateParamField(propName, prop, required.includes(propName), indent)); } }); return lines; } // --------------------------------------------------------------------------- // MDX generation — one file per group // --------------------------------------------------------------------------- function writeGroupMdx(groupName, signals, outputDir) { console.log(`\n🔍 Processing group: ${groupName} (${signals.length} signals)`); const lines = []; lines.push('---'); lines.push(`title: "${groupName} Signals"`); lines.push(`sidebarTitle: "${groupName}"`); lines.push('---\n'); signals.forEach(({ signalCode, signalName, description, bodySchema }) => { console.log(` ${signalName} (${signalCode})`); lines.push(`### ${signalName}`); lines.push(''); lines.push(`GET \`/vehicles/{vehicleId}/signals/${signalCode}\``); lines.push(''); if (description) { lines.push(description); lines.push(''); } if (bodySchema) { const properties = bodySchema.properties || {}; const required = bodySchema.required || []; lines.push(''); lines.push(' '); if (Object.keys(properties).length > 0) { lines.push(...handleNestedProperties(properties, required, ' ')); } if (bodySchema.example !== undefined) { lines.push(''); lines.push('```json Example'); lines.push(JSON.stringify(bodySchema.example, null, 2)); lines.push('```'); } lines.push(' '); lines.push(''); } lines.push(''); }); 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 fs.readdirSync(outputDir).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 ${f}:`, err); } } }); fs.writeFileSync(outPath, lines.join('\n'), 'utf8'); console.log(`✅ Wrote ${outPath}`); } // --------------------------------------------------------------------------- // Snippets // --------------------------------------------------------------------------- function writeSnippet(groups, outputFile) { const lines = Object.keys(groups) .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase())) .map(group => `- [${group}](/api-reference/signals/${group.toLowerCase()})`); lines.push(''); const dir = path.dirname(outputFile); if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(outputFile, lines.join('\n'), 'utf8'); } // --------------------------------------------------------------------------- // docs.json // --------------------------------------------------------------------------- function updateDocsJson(groupNames) { const docs = JSON.parse(fs.readFileSync(DOCS_JSON_PATH, 'utf8')); let found = false; (docs.navigation?.tabs || []).forEach(tab => { (tab.groups || []).forEach(groupObj => { if (groupObj.group === 'Smartcar Signals & Attributes' && Array.isArray(groupObj.pages)) { const newPages = groupNames.map(name => `api-reference/signals/${name}`); const pageSet = new Set(groupObj.pages.map(p => p.toLowerCase())); newPages.forEach(p => pageSet.add(p)); const allPages = Array.from(pageSet); const hasSchema = allPages.some(p => p.toLowerCase() === SCHEMA_NAV_PATH); let rest = allPages .filter(p => p.toLowerCase() !== SCHEMA_NAV_PATH) .sort((a, b) => a.split('/').pop().localeCompare(b.split('/').pop())); groupObj.pages = hasSchema ? [SCHEMA_NAV_PATH, ...rest] : rest; found = true; } }); }); if (found) { fs.writeFileSync(DOCS_JSON_PATH, 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'); } } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- function main() { console.log(`📥 Reading: ${VEHICLE_SIGNALS_PATH}`); const spec = loadYaml(VEHICLE_SIGNALS_PATH); const paths = spec.paths || {}; // Extract and group signals by their first tag const groups = {}; Object.entries(paths).forEach(([pathKey, pathItem]) => { const op = pathItem.get; if (!op) return; const tag = (op.tags || [])[0]; if (!tag) return; const signalCode = pathKey.split('/signals/')[1]; if (!signalCode) return; const responseSchema = op.responses?.['200']?.content?.['application/json']?.schema; const attrsProps = responseSchema?.properties?.attributes?.properties; const signalName = attrsProps?.name?.example || signalCode; const bodySchema = attrsProps?.body || null; const description = bodySchema?.description || ''; if (!groups[tag]) groups[tag] = []; groups[tag].push({ signalCode, signalName, description, bodySchema }); }); // Write per-group MDX files Object.entries(groups).forEach(([groupName, signals]) => { writeGroupMdx(groupName, signals, OUTPUT_DIR); }); // Write snippets writeSnippet(groups, path.resolve(SNIPPETS_DIR, 'signals.mdx')); // Update docs.json nav const groupNames = Object.keys(groups).map(g => g.toLowerCase()); updateDocsJson(groupNames); console.log(`\n✅ MDX files generated for ${Object.keys(groups).length} groups in /api-reference/signals/`); } main();

Changelog

Previous

Documentation Index

​May 10, 2024

​May 8, 2024

May 10, 2024

May 8, 2024