Skip to content

README.md

Latest commit

 

History

History
112 lines (94 loc) · 5.05 KB

README.md

File metadata and controls

112 lines (94 loc) · 5.05 KB
Raw

RoadMaker documentation

The documentation home: what lives where, and the fastest reading path for what you want to do.

RoadMaker is an open-source (Apache-2.0) road-network authoring toolkit for autonomous-driving simulation — a C++20 kernel with Python bindings and a Qt 6 Widgets editor, centered on ASAM OpenDRIVE correctness. This docs/ tree is the single source of truth for the project's standards, architecture, domain conventions, and roadmap.

I want to build and run it

  1. Building — Qt provisioning, CMake presets, all three platforms, troubleshooting.
  2. Running — the editor, sample files, the Python package.
  3. Repository tour — what each folder is.

I want to author a network

The user guide is task-by-task guidance for building an OpenDRIVE scene in the editor: Create Road, Edit Nodes, Lane Profile, Elevation, Junction, Objects & signals, and Save & export.

I want to contribute

  1. Workflow — branches, conventional commits, what rides along every change.
  2. Pull requests — the PR checklist and review process.
  3. Testing — GoogleTest/pytest doctrine, headless Qt tests, sanitizers, fuzzing.
  4. CI — what each gate checks.
  5. Writing user documentation — which tier a page belongs to, and what syntax each one allows.
  6. Publishing the documentation site — how a merged docs change reaches a live page, and the maintainer runbook for the hosting app.
  7. The standards your change must meet: C++ style · Cross-platform · Dependencies & licensing · Assets · Product parity & IP · UI design

I want to understand the architecture

  1. Overview — the three layers and the rules between them.
  2. Kernel — data model, geometry, I/O, meshing, exporters.
  3. Editor — Document/SelectionModel, undo, renderer.
  4. Python bindings — the nanobind layer.
  5. Persistence layers — what lives in the .xodr, what lives beside it, and why.
  6. Domain background: OpenDRIVE conventions · OpenSCENARIO scenarios · Geometry & meshing · Realism defaults · GIS import · OSM mapping · ASAM references

Where is the project going?

  • Roadmap — "Road to Parity" — the eight capability pillars, their sequencing, the sprint conventions, and the single-release gate. The README section is a summary of this page.
  • Golden workflows — the hand-executed acceptance scripts (GW-1 … GW-5) that every pillar feeds; the roadmap's only acceptance mechanism.
  • Archive — the retired milestone/version roadmap, golden scenes, seeds, and release notes, kept as a historical record.

Design documents and decisions

  • design/ — full design docs per initiative (M2 editing framework, hardening, UI revamp, materials & structures). These are written when an initiative's planning task runs.
  • decisions/ — Architecture Decision Records (ADRs): one page per significant, hard-to-reverse decision. Start new ones from the template.

Documentation conventions

Every page in this tree follows these rules — apply them when adding or editing docs:

  • One H1 per file; sentence-case headings.
  • Every page opens with a 1–2 line statement of what the page is for.
  • Relative links only for in-repo targets; a rule lives on exactly one page and everything else links to it.
  • Runnable commands go in fenced code blocks and are tested on at least the platform you develop on.
  • No page over ~300 lines — split instead.
  • Diagrams are Mermaid, inline in the page.

The tree is plain Markdown. docs/user-guide/ is additionally the authored source for two generated outputs — the in-app help book and the documentation site (ADR-0009) — which constrains what may be written there; see Writing user documentation. The rest of docs/ has no pipeline and no syntax budget.