feat(docs): docs viewer, API reference generator, markdown rendering
- Add YAML frontmatter (title/order/category) to 13 docs/*.md files
- Add services/docs_service.py: mtime-cache, frontmatter parsing w/ fallback,
bleach sanitize, path traversal protection
- Add routes/docs.py: GET /api/docs, GET /api/docs/<slug>, GET /api/docs/api-reference
- Register docs_bp in app.py
- Add frontend /docs + /docs/[slug] routes (sidebar nav + markdown render)
- Add frontend/src/types/docs.ts interfaces
- Add link from /help page to /docs viewer
- Add scripts/validate_docs.py: frontmatter + broken link validation
- Add elemes.sh docs-validate command
Endpoints documented in API reference: /quiz-attempts/<lesson>,
/sessions, /bab/<folder>, /compile/sessions, /lesson/<slug>.json + all 30 routes
2026-08-17 11:29:43 +07:00
---
title: Lesson Evaluation
order: 4
category: evaluation
---
2026-05-14 16:33:45 +07:00
# 04. Lesson Evaluation
The LMS determines the type of lesson and how to evaluate it based on specific markers found in the Markdown content.
## Markdown Markers
| Mode | Marker | Evaluation Logic |
|------|--------|------------------|
| **C / Python** | `---INITIAL_CODE---` / `---INITIAL_PYTHON---` | Standard stdout matching against `---EXPECTED_OUTPUT---` and presence of `---KEY_TEXT---` . |
| **Circuit** | `---INITIAL_CIRCUIT---` | Node voltage matching against `---EXPECTED_CIRCUIT_OUTPUT---` and `---KEY_TEXT_CIRCUIT---` . |
| **Arduino (Velxio)** | `---INITIAL_CODE_ARDUINO---` | Serial output sequence matching, lenient graph wiring comparison, and `---KEY_TEXT---` . |
| **Quiz** | `---QUIZ_FLASHCARD---` | State completion tracking (all questions answered correctly). |
2026-05-14 19:04:24 +07:00
| **Slide** | `---slide-start---` | Tidak ada (hanya presentasi konten). |
2026-05-14 16:33:45 +07:00
## Evaluators (`lib/services/`)
The evaluation logic is isolated into specific service files:
### General & C/Python (`evaluators.ts`, `exercise.ts`)
- `export function checkKeyText(code: string, keyText: string): boolean`
Checks if all lines in the `keyText` are present in the provided `code` .
- `export function processLanguageEvaluation(...)`
Coordinates the compilation request and output verification for C and Python.
### Circuit Evaluation (`evaluators.ts`, `exercise.ts`)
- `export function evaluateCircuitSubmission(...)`
Handles the flow of extracting the circuit state.
- `export function validateNodes(actualVoltages: Record<string, number>, expectedNodes: Record<string, NodeResult>): boolean`
Validates if the actual node voltages match the expected voltages within a specified tolerance.
### Arduino/Velxio Evaluation (`velxio-evaluator.ts`, `velxio-bridge.ts`)
- `class VelxioBridge` (`velxio-bridge.ts`)
Manages the `window.postMessage` protocol between the LMS and the Velxio iframe.
- Commands: `elemes:load_code` , `elemes:load_circuit` , `elemes:get_source_code` , `elemes:get_serial_log` , `elemes:get_wires` .
- Events: `velxio:ready` , `velxio:compile_result` .
- `export function evaluateVelxioSubmission(...)`
Orchestrates the 3-part Arduino evaluation:
1. **Key Text** : Checks the retrieved source code.
2. **Serial Output** : Uses `matchSerialSubsequence(actual, expected)` to ensure expected log lines appear in the correct order.
3. **Wiring** : Performs a lenient graph comparison (expected edges must exist; extra edges are allowed; ground pins are normalized).
### Flowchart Evaluation (`flowchart-evaluator.ts`)
- `export function evaluateFlowchartSubmission(...)`
Parses flowchart JSON data and verifies structural correctness against the expected model.
