Reference

Quick lookups: what round-trips, the compatibility promise, and answers to common questions.

Keyboard shortcuts

The editor supports keyboard navigation for the tree, find/filter, and the read/edit toggle, with visible focus throughout. The exact key map is shown in-app; every interactive control (tree, filters, tabs, copy buttons) is keyboard-operable.

RST round-trip and compatibility

TheoWorks reads and writes standard sphinx-needs RST. Editing a need writes a minimal, clean diff and is byte-stable — the parts of a file you did not touch are left exactly as they were. Content TheoWorks did not author (generated or imported needs) is treated read-only, so it is never corrupted or lost. Your project continues to build with plain Sphinx + sphinx-needs.

Compatibility promise

TheoWorks is designed to sit on top of existing sphinx-needs repositories without disrupting them. It reads the project's own schema, respects existing formatting, and produces reviewable diffs — so adopting TheoWorks does not require reformatting or migrating your repository.

FAQ and troubleshooting

I saved a change but validation / the graph didn't update. Why?

Your edit is Saved but probably not yet Built. Validation and the rendered needs graph update when the project is built (in CI or on the next build). See the change lifecycle in Core concepts.

A link shows as "dangling" — what does that mean?

The link points at a need id that does not exist in the project. Fix the target id, or create the missing need.

Can I use my own schema instead of a pack?

Yes. Packs are a starting point. After scaffolding, your project's live schema is its own conf.py and you can evolve it. See Project setup.

Is my data sent anywhere when self-hosting?

No. Self-hosted TheoWorks runs on your infrastructure against your Git repo; your data never leaves it.