Add documentation generator with built-in validation for reference docs

[blindzero]

Motivation / Problem

As the IdLE documentation grows (events, providers, configuration, steps, …), we need a consistent, enforceable structure for reference documentation.

Today:

• Some Reference docs are written manually
• Consistency is enforced only by reviews
• Mandatory sections can be forgotten or implemented differently

We want a single PowerShell-based tool that:

• Ensures mandatory sections are present (validation / linting)
• Can optionally generate reference docs from templates (generation)
• Works cross-platform and without external dependencies
• Integrates cleanly into CI

Goal

Provide a single documentation tool that supports both:

• Validation mode (acts as a linter)
• Generation mode (scaffolds or updates reference docs)
• This avoids having separate tools and ensures a single source of truth for documentation structure.

Scope

• Validation of docs/reference/**/*.md
• Mandatory section enforcement
• Optional generation from templates
• CI-friendly exit codes

❌ Out of scope:

• Markdown AST parsing
• Auto-generation of full content from code
• Rewriting existing docs without explicit markers
• Non-reference documentation (getting-started, advanced, etc.)

Proposed Tooling

Script location: tools/Invoke-IdleDocs.ps1
Supported modes

pwsh ./tools/Invoke-IdleDocs.ps1 -Validate
pwsh ./tools/Invoke-IdleDocs.ps1 -Generate

Mandatory Reference Structure (initial)

Each reference document under docs/reference/** must contain:

• <Title>

• Purpose

• Scope

• Concept

• Usage

• Common pitfalls

• Related documentation

Notes:

• Order should be recommended but not strictly required
• Section titles are matched by heading text (regex-based)
• Case-insensitive

Validation Mode (-Validate)

The validation mode must:

• Scan all docs/reference/**/*.md
• Verify that all mandatory sections exist
• Optionally detect placeholders like TBD, TODO
• Output clear, actionable error messages
• Exit with non-zero code if validation fails

Example output:

[ERROR] docs/reference/events-and-observability.md
        Missing section: "Common pitfalls"

Generation Mode (-Generate)

The generation mode should:

• Create new reference docs from templates
• Use a template file, e.g.: templates/reference.md
• Be idempotent
• Only overwrite explicitly marked sections (e.g. )
• Never destroy manual content without clear markers
• Initial implementation may be minimal (scaffolding only).

Design Constraints

• PowerShell Core 7 only
• No external dependencies
• Deterministic output
• Clear separation between:
  • tooling
  • documentation content
  • Must run in CI environments

Acceptance Criteria

• Invoke-IdleDocs.ps1 -Validate fails CI if reference docs violate structure
• Validation errors are clear and actionable
• Generator can scaffold a new reference doc from a template
• Tool is documented in CONTRIBUTING.md or docs/
• No impact on core engine code

Related Issues

• add event and observability reference #31 – Event & Observability Reference
• add provider and contract reference #30 – Provider & Contract Reference
• docs: add configuration reference #29 – Configuration Reference

Rationale

This approach:

• Prevents documentation drift
• Keeps documentation quality enforceable
• Scales with future reference docs
• Avoids over-engineering (no AST, no Markdown parser)
• Fits IdLE’s philosophy: portable, testable, modular

[blindzero]

Not sure if / when to add...
In general YES. We want to generate references automatically and reach completeness and consistency by that.
However, it seems to be hard to reach in PoSH. So postponing and maybe rethinking to have a docs.idleengine.io page later.