Glossary¶

The vocabulary used throughout this documentation, in one place. Key concepts introduces the same ideas in prose and in the order you meet them; this page is the lookup form, and every entry here is a link target — write :term:`need` anywhere in your own docs and it resolves to the entry below.

directive¶: A block-level construct that starts with .., followed by a name and ::. Every need type you declare becomes a directive.
field¶: A named piece of metadata carried by a need, such as status or tags. Some fields are built in (id, title, status, tags); you can declare your own, with an optional JSON Schema that is validated at index time, before the docs are built.
index¶: The model ubCode builds from your project. It indexes every source file belonging to one ubproject.toml, together with imported and external needs, and any change to those files is reflected immediately. It is what makes diagnostics, link resolution and traceability data available without a full Sphinx build.
link type¶: A named relationship between needs, such as implements, tests or depends on. Each link type has an outgoing label and an incoming label, so the relationship reads correctly from both ends.
need¶: A structured, traceable item inside your documentation — a requirement, specification, test case, user story, or any other artefact you want to track, written in plain text alongside your docs. Every need has at least a type, an ID and a title.
need type¶: A category of need, which gives that category its own directive. A type declares its directive name, its ID prefix and its diagram colour, so writing .. req:: tells ubCode the item is a requirement.
reStructuredText¶
RST¶: The lightweight markup language Sphinx uses to write documentation. If you have used Markdown it will feel similar, but it adds directives and roles for richer, structured content.
role¶: An inline construct written as :rolename:`text`. Sphinx-Needs provides the :need: role, for example, to create a clickable reference to a need.
traceability marker¶: A marker embedded directly in a source-code comment. ubCode’s engine scans those comments, extracts the markers, and converts them into need objects — so requirements can live next to the code that implements them.
ubproject.toml¶: The configuration file that tells ubCode about your project — which need types exist, what link types to use, where your source files are, and how linting should behave. It uses TOML rather than a Python conf.py because ubCode cannot execute Python and a TOML file can be parsed in microseconds.
variant¶: An expression that lets a field or link value change depending on the current build context. You write it inside the field value and ubCode evaluates it at index time to pick the right result — one set of sources describing every product variant, with a tailored output per build.