README.md

Document Generation Manual

OpenSysML generates documents from SysML v2 models: queries written in the model collect and shape elements, a document definition written in the model arranges them into sections, paragraphs, tables, lists and diagrams, and the engine renders the result as Markdown, HTML or PDF. The whole document — content and structure alike — lives in the model, so the report regenerates whenever the model changes.

This manual is the guide to that pipeline. Every SysML snippet in it parses and renders with the current sysml binary, and every rendered output shown was produced by it.

1. Introduction and concepts — queries, documents, content blocks, and the model → queries → document → Markdown/HTML/PDF pipeline
2. Getting started — the smallest working document, end to end
3. Query cookbook — recipes for collecting, filtering, sorting, traversing and projecting model elements
4. Which query is which — document queries beside the API Query, Evaluate, all T and solve: what each reads, returns and cannot see, and where the runtime's state and event queries sit
5. Document authoring — sections, paragraphs, inline runs, links, cross-references, tables (including grouped tables), lists and diagrams
6. Outputs — Markdown, semantic HTML and its stylesheets, the PDF engines and their options, and what determinism is guaranteed
7. Interfaces — CLI flags, REPL commands, the gRPC and Python APIs, and VS Code/LSP authoring support
8. A complete worked example — a telescope mass report with its full source and full rendered output; the traceability example (source) renders every requirement's satisfiers, verifiers and verdicts in one report
9. Requirements traceability examples — four graded reports, from three flat requirements and their satisfiers to a multi-team program with derivation chains, verdicts, coverage gaps and a grouped matrix, each with its source and rendered output
10. Limitations and troubleshooting — the typed error catalog and the current limitations

The document-query vocabulary is a non-normative OpenSysML extension — it is not part of the OMG SysML v2 or KerML standard. Models that use it remain standard SysML v2: the vocabulary is ordinary calc defs and part defs from the bundled DocumentQueries library package, and using it does not alter the language's semantics.