TopoExec Documentation¶
This directory is the canonical documentation root. The project is complex enough to use numbered zones: first contact and user learning paths come first, developer and architecture material live in 2x, planning and decision history in 3x, tools and standards in 4x, and reference material in 6x.
Reader Paths¶
- New user: project map -> getting started -> examples guide -> cookbook.
- Embedder: API overview -> public API stability -> runtime architecture.
- Maintainer: maintainer map -> codebase map -> testing strategy -> live observe performance.
- Planner or release owner: goal backlog -> goal status -> release and adoption readiness -> release runbook -> beta readiness review -> v1 readiness program.
Zones¶
| Zone | Purpose | Start here |
|---|---|---|
00-start-here |
First-contact map and orientation. | Project map |
01-quickstart |
Fastest safe local build and first execution. | Getting started |
10-user-overview |
Product vocabulary, FAQ, and comparison context. | Concepts |
11-user-guide |
Stable usage guides for graph authors and example readers. | Cookbook |
12-integrations |
Adapter, FFI, Python, and plugin preview boundaries. | Adapter boundaries |
20-development-overview |
Maintainer entry point and development map. | Maintainer map |
21-architecture |
Stable architecture, runtime semantics, and boundaries. | Runtime architecture |
22-codebase |
Source tree and ownership map. | Codebase map |
24-testing |
Test strategy, fuzz/stress/bench evidence, and defensive input checks. | Testing strategy / Reliability program |
31-planning-roadmap |
Current backlog, goal status, active blockers, and roadmap records. | Goal backlog / Ecosystem decision gate / Conditional tracks ledger |
33-specs-rfcs |
Schema and proposal-like design notes. | Schema v1 |
41-development-tools |
CLI, quality gates, editor/schema tooling, live validation, examples/showcase workflow, and agent helpers. | Quality gates / CLI / Examples and showcase / Live runtime validation |
43-ci-build-release-tools |
Build, package, release, versioning, adoption readiness, and baseline evidence. | Build and package / Package matrix / Release and adoption readiness / Core runtime beta candidate / v1 readiness program |
44-coding-standards |
Contribution and coding process standards. | Contributing / Feedback and triage |
45-doc-standards |
Documentation conventions, Pages publishing, and maintenance rules. | Documentation system / GitHub Pages |
61-api |
Public C++/C API, compatibility, and generated reference entry points. | API overview / Doxygen |
62-schemas-protocols |
Metrics, trace, diagnostic, and live observe output schemas. | Metrics / Live observe events |
Stability Notes¶
Stable guidance describes current runtime, API, schema, test, and release behavior. Planning docs under 31-planning-roadmap are compact status surfaces and should not duplicate implementation docs, CI logs, or release artifacts.
Adapter, C API, Python, editor, plugin, live dashboard, and README showcase docs are explicit preview, local-tooling, or boundary surfaces unless their page says otherwise. Live observe is an observability/test-validation path, not a runtime control path. Do not infer production ROS 2, production OpenTelemetry/Prometheus, native Python bindings, stable ABI, schema v2 implementation, migration CLI, remote dashboard access, pause/resume/step/fault injection, or sandbox support from preview docs.
Docs Validation¶
The docs_command_smoke CTest runs selected commands embedded as topoexec-doc-test markers across this tree. It also checks that required navigation pages and section contracts remain present after moves.
The optional Pages build uses MkDocs plus Doxygen through
scripts/docs_build_site.sh. It publishes the Markdown site and copies
generated API HTML under /api/; normal runtime builds do not require docs
tooling.