Voltimax Platform

Appearance

Documentation Workflows ​

This guide covers common documentation workflows and step-by-step procedures.

Adding a New Feature Guide ​

1. Choose the Right Section ​

Determine where your documentation belongs:

  • Operator task? > /docs/guide/
  • Integration task? > /docs/integration/
  • Developer task? > /docs/developer/

See Structure for details.

2. Select a Template ​

Pick the appropriate template for your content:

See Templates for the decision flowchart.

3. Write the Content ​

  1. Create your Markdown file in the appropriate directory
  2. Use the structure from Templates as your starting point
  3. Follow the writing guidelines

4. Update Navigation ​

Add your page to the appropriate sidebar:

Example: Adding to User Guide ​

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

typescript
{
  text: 'Getting Started',
  items: [
    { text: 'Installation', link: '/guide/installation' },
    { text: 'Your New Page', link: '/guide/your-new-page' }  // Add here
  ]
}

5. Test Locally ​

bash
cd docs
npm run docs:dev

Verify:

  • Page renders correctly
  • All links work
  • Code examples display properly
  • Images load
  • Navigation is correct

6. Commit Changes ​

bash
git add docs/
git commit -m "docs: add guide for [feature name]"
git push

Updating Generated Documentation ​

When schemas change, regenerate the reference documentation.

1. Update the Schema Source ​

Edit the appropriate schema file:

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

2. Regenerate Documentation ​

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

# Or regenerate specific schema only
.\cli.ps1 schema metrics docs

3. Review Changes ​

bash
git diff docs/reference/

Verify:

  • New content is correct
  • Formatting is consistent
  • Links are valid
  • No unintended changes

4. Commit Both Schema and Docs ​

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

Documenting a New Protocol ​

Workflow for adding a new protocol with auto-generated docs.

1. Add Schema Files ​

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

2. Create Generator ​

bash
mkdir -p tools/Voltimax.Iot.Tools/Schema/[Protocol]/

Create these files:

  • [Protocol]SchemaParser.cs - Parse schema files
  • [Protocol]DocsGenerator.cs - Generate Markdown
  • Generate[Protocol]Command.cs - CLI command

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. Update GenerateAllCommand ​

Edit tools/Voltimax.Iot.Tools/Schema/GenerateAllCommand.cs:

csharp
public int OnExecute()
{
    // ... existing generators
    
    Log.Information("Generating [Protocol] documentation...");
    var protocolCmd = new GenerateProtocolCommand();
    protocolCmd.OnExecute();
    
    return 0;
}

5. Create Sidebar ​

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

typescript
export default [
  {
    text: '[Protocol] Reference',
    items: [
      { text: 'Overview', link: '/reference/[protocol]/' }
      // Generator will populate more items
    ]
  }
]

6. Update Reference Sidebar ​

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

typescript
import protocol from './[protocol]'

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

7. Generate Documentation ​

bash
.\cli.ps1 generate --[protocol]

8. Test and Commit ​

bash
cd docs
npm run docs:dev

# Verify output, then commit
git add schemas/ tools/ docs/
git commit -m "feat: add [protocol] documentation generation"

Resources ​