Skip to content

Latest commit

 

History

History
58 lines (44 loc) · 3.04 KB

README.md

File metadata and controls

58 lines (44 loc) · 3.04 KB

dsoxlab documentation

Audience: this page is a switchboard, and belongs to no one in particular. Every other page names its reader in its first lines, because a document that answers three people at once answers none of them.

Language: English · Français

dsoxlab turns declarative exercises into reproducible, runnable and verifiable lab environments. The repository README says what it is in thirty seconds; these pages say how it works.


The three doors

Page For you if…
For the learner You install dsoxlab, play labs and want to understand your score
For the catalog author You write labs in your own repository
For the trainer You run the machines and providers the labs need

There is a fourth door for those who would rather not install anything: the appliance, a ready-to-play virtual machine, for Windows and macOS.

References

Page Content
The v1 contract meta.yml and lab.yaml, field by field, with what version 1 guarantees
Command reference Every command, generated from the CLI itself
Where dsoxlab writes Every file dsoxlab creates, and the environment variables it reads
Infrastructure without labs Using dsoxlab as a provisioner of throwaway VMs, without writing a single exercise
The machine output What --json prints, field by field, and what may be built on it
Exit codes Every code the CLI returns, what it means, and the gesture it calls for
The security model Where the trust boundary runs, what the engine refuses to do, and what it does not protect you from
Design principles The invariants, each with the incident that revealed it and the test that holds it — and what the project promises to whoever integrates it
Architecture decisions Why each durable choice was made: its context, what was rejected, what it costs and what would reverse it
The mark Name, logo and their usage terms

Contributors have CONTRIBUTING.md: setup, quality gates, architecture map and commit conventions.


Two habits worth borrowing

Nothing here is written twice. The command table is generated from the CLI, and the file locations are checked against the code by tests/test_documentation_synchrone.py, which derives them by calling the same functions the CLI calls. Both controls exist because both had already drifted: the command table described a cleanup.sh the contract forbids, and the persistence section pointed at a database that never existed.

These pages are Markdown in the repository, deliberately. There is no site generator here, so the documentation is read where it is written, versioned with the code that it describes, and reviewed in the same pull request.