RLC Analyzer – Documentation Generator
======================================

This folder contains utility scripts used during development of the
RLC Analyzer project.

The main tool here is:

    gen_value_docs.mjs

This script generates and maintains the Value Reference documentation
for all simulator metrics and controls.

---------------------------------------------------------------------

Purpose
-------

The simulator exposes many calculated quantities (metrics) and controls.
The Value Reference provides detailed explanations for each of them.

The documentation pipeline works as follows:

    index.html
         ↓
    gen_value_docs.mjs
         ↓
    docs/value_registry.json
         ↓
    docs/value_reference.html

1) The generator scans the UI for metric and control IDs.
2) It merges them into the documentation registry.
3) It produces a structured documentation page.

The system is designed to be NON-DESTRUCTIVE.

Existing documentation entries are never overwritten.

---------------------------------------------------------------------

How to run the generator
------------------------

From the project root directory run:

    node tools/gen_value_docs.mjs

The script will:

• scan index.html for metric IDs
• update docs/value_registry.json
• generate docs/value_reference.html

---------------------------------------------------------------------

Important behavior
------------------

If a new metric is discovered in the UI:

• A new entry is automatically added to the registry
• The entry will contain empty documentation fields

Example:

{
  "id": "newMetric",
  "label": "New metric",
  "kind": "readout",
  "symbol": "",
  "name": "",
  "units": "",
  "definition": "",
  "meaning": "",
  "where": "",
  "related": [],
  "notes": ""
}

The operator must then fill in the documentation fields manually.

---------------------------------------------------------------------

WARNING
-------

Do NOT manually edit the generated HTML file:

    docs/value_reference.html

This file is regenerated automatically.

All documentation must be written in:

    docs/value_registry.json

---------------------------------------------------------------------

Typical workflow
----------------

1) Add new metric to the simulator UI

2) Run:

    node tools/gen_value_docs.mjs

3) Open:

    docs/value_registry.json

4) Fill in the documentation fields

5) Re-run generator if needed

---------------------------------------------------------------------

Project

RLC Analyzer – Analytical Reference & Visualization Lab
A reference-grade analytical RL/RLC circuit analysis instrument.
