TheoWorks

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 page covers starting a new project, bringing an existing one, and how the schema works.

Start a new project

  • Web — sign in to the hosted app (from theoworks.io) and choose New project to pick a template: ASPICE (an Automotive SPICE traceability spine — stakeholder → system → software → architecture → unit, with verification levels), V-model (a classic V-model requirements/verification structure), or Blank (a minimal schema to start from scratch). TheoWorks scaffolds a buildable project you can start editing immediately. The public web demo is a single curated sample project and has no project picker — see the Quickstart.
  • Self-hosted — the launcher's Quick start seeds a sample project the first time the editor opens (see the Quickstart). To work on your own repository instead, run Set up team access and connect it — see Bring an existing sphinx-needs project below.

A template seeds your schema; after scaffolding, the project's live schema is its own conf.py — templates are a starting point, not a lock-in.

Bring an existing sphinx-needs project

TheoWorks reads your repository's own conf.py and needs — it never rewrites files it does not touch. To connect an existing repo:

What your repo needs:

  • sphinx-needs >= 8.0. Below that floor, TheoWorks still reads and edits content and only refuses to write configuration.
  • needs_build_json = True set in conf.py, so your Sphinx build emits needs.json.
  • A CI job that publishes needs.json as a build artifact, so the editor can find it. See CI integration for the job that produces it.

Do no harm: TheoWorks never rewrites content it did not author. Editing and saving a need writes a minimal, clean diff; the rest of the file is untouched, and your project keeps building with plain Sphinx.

Connect it:

  • Web / hosted — connect your GitLab from the onboarding flow.
  • Self-hosted — run the launcher's Set up team access wizard branch and point it at your own GitLab; see Self-hosting.

Once connected, TheoWorks reads the schema and needs straight from the repo — your existing content renders immediately.

Your schema (conf.py)

Your project's schema 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, and the statuses and their workflow transitions. This is what validation checks against and what the editor uses to offer the right fields and links.

It lives in two coordinated places: the native needs_* settings (which plain sphinx-needs understands), and an optional theoworks dict alongside them for per-type statuses, workflows, and id padding. A short excerpt, from a real ASPICE-flavored project:

python
needs_types = [
    {"directive": "sys-req", "title": "System Requirement", "prefix": "SYS-REQ-", "color": "#4338ca", "style": "node"},
    {"directive": "test", "title": "Test Case", "prefix": "TEST-", "color": "#b45309", "style": "node"},
]
needs_extra_links = [
    {"option": "satisfies", "incoming": "is satisfied by", "outgoing": "satisfies"},
    {"option": "verifies", "incoming": "is verified by", "outgoing": "verifies"},
]
needs_extra_options = ["asil"]
needs_build_json = True

theoworks = {
    "types": {
        "sys-req": {"statuses": ["draft", "reviewed", "approved"], "required_links": ["satisfies"]},
    },
}

Editing the schema is a first-class task — change it deliberately, since it governs every need in the project. See Reference → RST round-trip and compatibility for the compatibility promise this rests on.

Made with TheoWorks