Voltimax Platform

Appearance

Documentation Generation ​

All documentation in /docs/reference/ is automatically generated from schemas and should never be edited manually.

What's Auto-Generated ​

Metrics Reference ​

Source: schemas/metrics/metrics.json and registry files
Output: docs/reference/metrics/
Generator: tools/Voltimax.Iot.Tools/Schema/Metrics/

Generates comprehensive metrics documentation including:

  • Metric definitions by category
  • Units and data types
  • Descriptions and examples
  • Cross-references between related metrics

OCPP 2.1 Messages ​

Source: schemas/standards/ocpp/OCPP-2.1_all_files-3.zip
Output: docs/reference/ocpp/
Generator: tools/Voltimax.Iot.Tools/Schema/Ocpp/

Generates OCPP protocol documentation including:

  • Message schemas by category
  • Request/response pairs
  • Field definitions
  • Protocol requirements

SunSpec Models ​

Source: schemas/standards/sunspec/*.xml (SMDX files)
Output: docs/reference/sunspec/
Generator: tools/Voltimax.Iot.Tools/Schema/SunSpec/

Generates SunSpec model documentation including:

  • Model definitions by category
  • Register layouts
  • Data point specifications
  • Scale factors and units

Modbus Devices ​

Source: schemas/assets/modbus/*.yaml
Output: docs/reference/modbus/
Generator: tools/Voltimax.Iot.Tools/Schema/Asset/

Generates device-specific documentation including:

  • Register maps
  • Supported metrics
  • Connection parameters
  • Device-specific notes

How to Regenerate Documentation ​

Regenerate All Reference Docs ​

bash
.\cli.ps1 generate --ocpp-by-category --sunspec-by-category

This regenerates all reference documentation from current schemas.

Regenerate Specific Schemas ​

Metrics only:

bash
.\cli.ps1 schema metrics docs

OCPP only:

bash
.\cli.ps1 schema ocpp docs --by-category

SunSpec only:

bash
.\cli.ps1 schema sunspec docs --by-category

Modbus only:

bash
.\cli.ps1 schema asset docs

Configuration ​

Output paths are defined in tools/Voltimax.Iot.Tools/Shared/Constants.cs:

csharp
public const string MetricsDocsOutput = "docs/reference/metrics";
public const string OcppDocsOutput = "docs/reference/ocpp";
public const string SunSpecDocsOutput = "docs/reference/sunspec";
public const string ModbusDocsOutput = "docs/reference/modbus";

Generator dependencies are configured in GenerateAllCommand.cs.

When to Regenerate ​

Regenerate documentation whenever schemas change:

Schema File Changes ​

If you update any of these files, regenerate docs:

  • schemas/metrics/**/*.json
  • schemas/standards/ocpp/**/*
  • schemas/standards/sunspec/**/*.xml
  • schemas/assets/modbus/**/*.yaml

After Schema Updates ​

  1. Update the schema:

    bash
    # Example: Update battery metrics
vim schemas/metrics/registries/battery.json

  2. Regenerate documentation:

    bash
    .\cli.ps1 generate --ocpp-by-category --sunspec-by-category

  3. Review changes:

    bash
    git diff docs/reference/

  4. Commit both schema and docs:

    bash
    git add schemas/ docs/reference/
git commit -m "feat: add new battery metrics"

Generator Implementation ​

Each generator follows a similar pattern:

1. Schema Parser ​

Reads and validates the source schema:

csharp
// Example: MetricsSchemaParser.cs
public class MetricsSchemaParser
{
    public MetricsSchema Parse(string schemaPath)
    {
        // Read JSON schema
        // Validate structure
        // Return typed model
    }
}

2. Documentation Generator ​

Transforms schema into Markdown:

csharp
// Example: MetricsDocsGenerator.cs
public class MetricsDocsGenerator
{
    public void Generate(MetricsSchema schema, string outputPath)
    {
        // Group metrics by category
        // Generate markdown files
        // Create navigation
    }
}

3. CLI Command ​

Exposes generation via CLI:

csharp
// Example: GenerateMetricsCommand.cs
[Command("metrics", Description = "Generate metrics documentation")]
public class GenerateMetricsCommand
{
    public int OnExecute()
    {
        var parser = new MetricsSchemaParser();
        var generator = new MetricsDocsGenerator();
        
        var schema = parser.Parse(Constants.MetricsSchemaPath);
        generator.Generate(schema, Constants.MetricsDocsOutput);
        
        return 0;
    }
}

Adding a New Generator ​

To add documentation generation for a new protocol:

1. Add Schema Files ​

bash
mkdir -p schemas/standards/[protocol]/
# Add schema files

2. Create Generator ​

bash
mkdir -p tools/Voltimax.Iot.Tools/Schema/[Protocol]/
# Add parser and generator classes

3. Update Constants ​

Edit tools/Voltimax.Iot.Tools/Shared/Constants.cs:

csharp
public const string ProtocolDocsOutput = "docs/reference/[protocol]";
public const string ProtocolSchemaPath = "schemas/standards/[protocol]";

4. Create CLI Command ​

Add command in tools/Voltimax.Iot.Tools/Schema/[Protocol]/:

csharp
[Command("[protocol]", Description = "Generate [protocol] documentation")]
public class GenerateProtocolCommand
{
    // Implementation
}

5. Update GenerateAllCommand ​

Edit GenerateAllCommand.cs to include new generator:

csharp
public int OnExecute()
{
    // ... existing generators
    
    var protocolCmd = new GenerateProtocolCommand();
    protocolCmd.OnExecute();
    
    return 0;
}

6. Create Sidebar ​

Add docs/.vitepress/sidebar/[protocol].ts:

typescript
export default [
  {
    text: '[Protocol] Reference',
    items: [
      { text: 'Overview', link: '/reference/[protocol]/' },
      // Auto-populated by generator
    ]
  }
]

7. Update Reference Sidebar ​

Edit docs/.vitepress/sidebar/reference.ts:

typescript
import protocol from './[protocol]'

export default [
  // ... existing sections
  {
    text: '[Protocol]',
    collapsed: true,
    items: protocol
  }
]

Best Practices ​

Do ✅ ​

  • Regenerate docs immediately after schema changes
  • Commit both schema and generated docs together
  • Review generated output before committing
  • Keep generators idempotent (same input = same output)
  • Use consistent Markdown formatting
  • Generate navigation automatically
  • Include cross-references

Don't ❌ ​

  • Edit files in /docs/reference/ manually
  • Commit schema changes without regenerating docs
  • Create generators with side effects
  • Hardcode output paths
  • Generate documentation for hand-written content
  • Skip validation of schema files

Troubleshooting ​

Generated docs out of date ​

bash
# Regenerate all reference documentation
.\cli.ps1 generate --ocpp-by-category --sunspec-by-category

Generator fails ​

Check:

  • Schema files are valid (JSON/YAML syntax)
  • Output directory exists and is writable
  • All dependencies are installed
  • Generator code compiles

Verify:

  • Sidebar file exists and is imported
  • Links match generated file paths
  • config.mts includes sidebar mapping

Output path incorrect ​

Check Constants.cs has correct path definitions.

Resources ​