Reference

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

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 rendered needs didn't update. Why?

Your edit is Saved but probably not yet Built. Validation and the rendered needs 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 template?

Yes. A template is 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.