Project setup
A TheoWorks project is a sphinx-needs docs directory: a conf.py that declares
the schema, and RST files that hold the needs. This section covers starting from
a template, understanding the schema, and connecting an existing repository.
Templates and packs
TheoWorks ships packs — ready-made schemas plus a starter document tree for common processes:
- ASPICE — an Automotive SPICE traceability spine (stakeholder → system → software → architecture → unit, with verification levels).
- V-model — a classic V-model requirements/verification structure.
- Blank / default — a minimal schema to start from scratch.
You get a project from a pack in one of two ways:
- Web — choose New project and pick a template (see Templates & packs above).
- Self-hosted — the launcher's Quick start seeds a sample project on first run (see the Quickstart); to bring your own content, connect an existing repository (below).
A pack seeds your schema; after scaffolding, the project's live schema is its own
conf.py — packs are a starting point, not a lock-in.
Contributors working from a source checkout can also scaffold a pack from the
command line with the Python CLI: theoworks init --pack aspice my-project.
This is a developer tool (installed with the theoworks-cli package), separate
from the download-page launcher a self-host user runs.
The metamodel (schema admin)
Your project's metamodel is the set of rules in conf.py: the need types
(and their colours and id prefixes), the fields each type has, the links
allowed between types, the statuses and their workflow transitions, and
the id scheme (prefix + padding). This is what validation checks against and
what the editor uses to offer the right fields and links.
The schema lives in two coordinated places in conf.py: the native needs_*
settings (which plain sphinx-needs understands) and a theoworks sidecar
(per-type statuses, workflows, and field richness that TheoWorks adds). Editing
the schema safely is a first-class task — change it deliberately, since it
governs every need in the project.
Connecting an existing repo
Point TheoWorks at an existing sphinx-needs repository and it reads the project's
schema from conf.py and loads its needs. Because TheoWorks is git-native and
byte-stable, it fits into your existing repo and review process without
reformatting files it does not touch.
TheoWorks aims not to break existing sphinx-needs projects: your project still builds with plain Sphinx, and edits produce clean diffs. See Reference → RST round-trip & compatibility.