sysml-start — Project Overview

A text-first, docs-as-code SysML2 modeling workflow optimized for VS Code and easy onboarding of systems engineers. Model artifacts live in Git as plain text. Rendered diagrams and a navigable HTML documentation site are a day-1 capability.

Goals

  • Store all model artifacts as plain text files in Git

  • Enable editing in VS Code (or any text editor) without a GUI modeling tool

  • Render diagrams as SVG on day 1, embedded directly in Markdown documentation

  • Support command-line validate / render / build operations

  • Enable automated CI validation and doc generation via GitHub Actions

  • Structure the repository so an AI agent can draft artifacts and a human can review/approve via pull requests

Stakeholders

Stakeholder

Role

Systems Engineer

Authors and reviews model artifacts

AI Agent

Drafts model artifacts, views, and documentation

V&V Reviewer (Human)

Reviews AI-drafted content via GitHub PR; approves or requests changes

Documentation Consumer

Reads rendered HTML docs with embedded diagrams

CI System

Automatically validates and builds on every push and pull request

Artifact Flow

Model Files (.sysml)
       │
       ▼
 validate-model script
       │
       ▼
 render-diagrams script ──► generated/diagrams/*.svg
                                       │
                                       ▼
                             build-docs script ──► generated/docs/index.html
                                                   docs/*.md (with embedded SVG links)

Model files in model/ are the source of truth. Views in model/views/ define which diagram perspectives are rendered. The scripts/render-diagrams script reads the model and view definitions and produces SVG files. The scripts/build-docs script assembles those SVGs and the Markdown documents into a navigable HTML output.

Rendering Pipeline

model/*.sysml + model/views/*.sysml
         │
         │  SysMLInteractive REPL (OMG SysML v2 Pilot JAR)
         │  %viz <element>  →  @startuml...@enduml (PlantUML + sysmlbw skin)
         ▼
  tools/SysMLRender.java  (PlantUML Java API — skin resolved from JAR classpath)
         │
         ▼
generated/diagrams/context.svg
generated/diagrams/artifact-flow.svg
generated/diagrams/requirements.svg
         │
         │  (embedded in docs/workflow.md via Markdown image links)
         ▼
Rendered in VS Code Markdown Preview / GitHub / HTML export

The same pipeline applies to every view file. Adding a new view requires:

  1. Creating a new model/views/<name>-view.sysml file

  2. Adding a %viz <element> line and output filename in scripts/render-diagrams

  3. Embedding the resulting SVG in the appropriate Markdown document

What is Real vs Placeholder

Item

Status

.sysml model files

Real — valid SysML v2 syntax, verified by the OMG Pilot kernel

scripts/validate-model

Real — loads all files into the OMG Pilot REPL, reports errors

scripts/render-diagrams

Real — generates SVGs via OMG Pilot %viz + PlantUML Java API

scripts/build-docs

Real — builds a navigable HTML site via Sphinx + MyST (sphinx-rtd-theme); output in generated/docs/

Generated SVG diagrams

Real — laid out by GraphViz via the bundled PlantUML renderer

GitHub Actions workflows

Real — installs Java 21 + GraphViz, runs setup-tools, validates/renders/builds, and deploys docs to GitHub Pages

Next Steps

  • [ ] Add more model views (e.g., internal block, sequence, state machine)

Acknowledgements

  • OMG SysML v2 Pilot Implementation — the open-source reference implementation of the SysML v2 standard. This project uses the Pilot JAR for model validation and diagram rendering via the SysMLInteractive REPL and %viz commands.

  • PlantUML — diagram rendering engine bundled within the Pilot JAR.

  • GraphViz — graph layout engine used by PlantUML for SVG output.

  • Sphinx with MyST Parser — documentation toolchain used by scripts/build-docs.

  • sphinx-rtd-theme — Read the Docs theme for Sphinx HTML output.