EnerOS v0.44.0 Release Notes

• Release Date: 2026-06-29
• Codename: Docs
• Support Status: Stable
• Total Crates: 53
• Test Cases: 6850+
• Contributors: 22

Version Overview

EnerOS v0.44.0 is the fourth release of the “Mature Optimization” phase, focusing on the comprehensive restructuring and upgrade of the documentation system. Documentation is the bridge between open-source projects and developers. An excellent documentation system can shorten the learning curve from weeks to days. This release completely restructures the documentation site, introducing interactive tutorials, enhanced API documentation, and a systematic example library, building a complete learning path from beginner to advanced.

Building on the developer experience improvements in v0.43.0, this release further completes the “knowledge transfer” aspect. The new interactive tutorials allow developers to run Rust code snippets directly in the browser, experiencing EnerOS core capabilities without local installation. API documentation is upgraded from simple rustdoc to an enhanced version with call relationship graphs, cross-reference navigation, and online trial runs. The example library is organized by business scenarios, with each example being an independently runnable complete project.

The documentation site is rebuilt based on the Astro + Starlight framework, supporting Chinese and English bilingual content, full-text search, dark mode, and responsive layout. All documentation source files are under version control and released synchronously with code, ensuring documentation-code consistency.

Key Metrics

New Features

1. Documentation Site Restructuring

The documentation site migrated from the original Docusaurus to Astro + Starlight, gaining better performance, more flexible component customization, and better SEO performance. The new site uses a three-column layout (navigation / content / table of contents), supporting Chinese and English bilingual switching, full-text search, dark mode, and mobile responsive adaptation.

Site Architecture

eneros-web/
├── src/
│   ├── content/
│   │   ├── docs/           # Core documentation
│   │   │   ├── quick-start/    # Quick start
│   │   │   ├── concepts/       # Core concepts
│   │   │   ├── architecture/   # Architecture design
│   │   │   ├── capabilities/   # Capability details
│   │   │   ├── development/    # Development guide
│   │   │   ├── security/       # Security guide
│   │   │   ├── compliance/     # Compliance guide
│   │   │   └── releases/       # Release notes
│   │   ├── tutorials/      # Interactive tutorials
│   │   ├── examples/       # Example library
│   │   └── api/            # API documentation
│   ├── components/         # Custom components
│   │   ├── CodeRunner.tsx     # Online code execution
│   │   ├── ApiReference.tsx   # API reference
│   │   └── TopologyViewer.tsx # Topology visualization
│   └── styles/             # Global styles
├── astro.config.mjs
└── package.json

Documentation Frontmatter Specification

---
title: "Constraints as Law"
description: "Design philosophy and implementation principles of the EnerOS physical constraint engine"
category: "Core Concepts"
order: 3
---

Multi-language Configuration

// astro.config.mjs
import starlight from '@astrojs/starlight';

export default {
  integrations: [
    starlight({
      title: 'EnerOS',
      defaultLocale: 'zh',
      locales: {
        zh: { label: '简体中文', lang: 'zh-CN' },
        en: { label: 'English', lang: 'en-US' },
      },
      sidebar: [
        { label: '快速开始', link: '/quick-start' },
        { label: '核心概念', link: '/concepts' },
        { label: '架构设计', link: '/architecture' },
        { label: '能力详解', link: '/capabilities' },
        { label: '版本说明', link: '/releases' },
      ],
      search: {
        engine: 'pagefind',
        options: { fuzzy: true },
      },
    }),
  ],
};

2. Interactive Tutorials

Added 24 interactive tutorials covering a complete learning path from environment setup to advanced features. Each tutorial contains runnable code snippets. Developers can edit and run Rust code in the browser and see results in real-time. Tutorials run Rust in the browser via WebAssembly, requiring no local installation.

Tutorial Catalog

Online Code Execution Component

// Runnable code in interactive tutorials
use eneros_topology::{NetworkGraph, Bus, BusType, Voltage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut network = NetworkGraph::new();

    // Add buses
    network.add_bus(Bus::new(1, BusType::Slack, Voltage::new(1.05, 0.0)))?;
    network.add_bus(Bus::new(2, BusType::PQ, Voltage::new(1.0, 0.0)))?;

    // View topology
    println!("Bus count: {}", network.bus_count());
    println!("Island count: {}", network.topology().find_islands().len());

    Ok(())
}

Code blocks in tutorial pages have a “Run” button. Clicking it executes the code in the browser via WebAssembly, with output displayed in real-time below the code block.

3. API Documentation Enhancement

API documentation is upgraded from standard rustdoc to an enhanced version, adding call relationship graphs, cross-reference navigation, parameter descriptions, and online trial runs. All public APIs automatically generate documentation, synchronously updated with source code.

Enhanced Features

API Documentation Generation

use eneros_docs::api::{ApiDocGenerator, DocConfig};

let generator = ApiDocGenerator::new(DocConfig {
    input: "src/",
    output: "docs/api/",
    include_private: false,
    generate_call_graph: true,
    generate_examples: true,
    cross_reference: true,
});

generator.generate().await?;

API Documentation Structure Example

## `NetworkGraph::add_bus`

Adds a bus to the power grid topology.

### Signature

```rust
pub fn add_bus(&mut self, bus: Bus) -> Result<BusId, TopologyError>

Parameters

Return Value

Returns the newly allocated bus ID. If the bus ID already exists, returns TopologyError::DuplicateBus.

Example

let bus = Bus::new(1, BusType::PQ, Voltage::new(1.0, 0.0));
let bus_id = network.add_bus(bus)?;

Since

v0.40.0

### 4. Example Library

The example library is organized by business scenarios, containing 36 independently runnable complete projects. Each example contains complete source code, test cases, deployment configuration, and documentation. Developers can directly use them as project starting points.

#### Example Categories

| Category | Example Count | Typical Examples |
|------|--------|---------|
| Basic examples | 8 | Topology operations, power flow computation, constraint validation |
| Agent examples | 10 | Dispatch Agent, forecast Agent, diagnosis Agent |
| Protocol access | 6 | IEC 104, Modbus, MQTT, CoAP |
| Industry solutions | 7 | Microgrid, demand response, new energy, charging stations |
| Integration examples | 5 | Prometheus, Grafana, Kafka, Hadoop |

```bash
# Clone example library
eneros-cli project new my-project --example economic-dispatch

# Or run example directly
cd examples/economic-dispatch
eneros-cli dev run

Improvements

Full-Text Search

The documentation site integrates the Pagefind full-text search engine, supporting fuzzy matching, Chinese word segmentation, and search result highlighting. The search index is automatically generated at build time, requiring no server-side support.

Documentation Versioning

Each version’s documentation is saved independently, supporting version switching. Developers can view any version’s documentation to understand API differences across versions.

Code Example Testing

All code examples in documentation are included in CI testing, ensuring code examples are always compilable and runnable. Uses mdbook-test or rustdoc’s doctest mechanism.

# Run documentation tests
cargo test --doc
eneros-cli docs test

Dark Mode

The documentation site follows the system theme by default, supporting light/dark mode switching. Code blocks use dark background and syntax highlighting in dark mode.

Bug Fixes

• BG-501: Documentation site table of contents overflow on mobile, fixed responsive layout
• BG-505: Inaccurate Chinese search word segmentation, switched to jieba tokenizer
• BG-509: API documentation call relationship graph rendering too slow in large projects, changed to lazy loading
• BG-513: Interactive tutorial WebAssembly loading failure in Safari, fixed
• BG-517: Some example library dependency versions inconsistent with main project, unified alignment

Breaking Changes

BC-231: Documentation URL Structure Change

Documentation site URL changed from /docs/v0.43/xxx to /docs/xxx (latest version) and /docs/v0.43/xxx (historical version). Old URLs auto-redirect.

BC-232: eneros-docs Toolchain API Restructuring

The Rust API of the documentation generation tool has been restructured. Custom documentation generators need to adapt to the new interface.

Dependency Upgrades

Upgrade Guide

Upgrade from v0.43.0

This release has no runtime breaking changes. Upgrading only requires updating the documentation toolchain:

cargo update
cd eneros-web && npm install
npm run build

Update local documentation dependencies:

[dev-dependencies]
eneros-docs = "0.44"

Related Documentation

• Documentation Writing Guide - Documentation contribution guidelines
• Interactive Tutorials - Online learning center
• API Reference - Complete API documentation
• Example Library - Code example index