Variants¶

Variants let one set of sources serve several build configurations — different platforms, editions, or targets — by keeping the union of all of them in a single model and letting each build select what applies. The preview evaluates these mechanisms against your configured variant data, so you can see what a given variant produces without running a build.

The concept and the full workflow — the “150% model”, producing a build per variant, and comparing variants — are owned by the Variant builds guide. This page covers only what the preview renders for the two constructs you write in your content: the if directive and the variant role (plus a note on variant field values).

This reference describes the Rendered preview mode; in Structural mode every directive and role renders as a uniform placeholder (see Authoring).

The `if` directive¶

The if directive conditionally includes a whole block of content — paragraphs, admonitions, tables, lists, needs, anything you can nest — based on an expression evaluated against your variant data. Its argument is the condition; the content it wraps is the body:

.. if:: var.platform == "windows"

   .. note::

      This note is only shown for the Windows build.

Because it wraps arbitrary block content, the same directive can gate a whole need just as easily as a paragraph:

.. if:: var.platform == "windows"

   .. req:: Windows power management
      :id: REQ_WIN_PM

      This requirement only exists in the Windows variant.

When the condition is truthy, the body renders exactly as if the if wrapper were not there — a need inside it is shown, collected, and indexed normally. When the condition is falsy, or cannot be evaluated, the body is kept visible but collapsed and greyed out, labelled with its condition. This is a deliberate difference from a Sphinx-Needs build, which omits the block entirely (see Differences from a Sphinx build); the preview is a development tool, so seeing that inactive content exists — and why — is useful. An expression that is invalid — an unknown var.* key, a syntax error, or a type mismatch — is reported as a diagnostic, and its body is treated as falsy.

The full expression language the condition accepts, and the way the editor fades an inactive source region (like disabled code in a C editor), are documented under 4. Conditional content with the if directive.

The `variant` role¶

:variant: resolves its content against your configured variant data and shows the resolved value as plain text. The content is a dotted path into that data:

Building for :variant:`build.target`.

The value is looked up in the current variant’s data and rendered inline as plain text — a list joins with commas, and booleans and numbers use their plain form.

When the value cannot be resolved — an unknown key, a path that does not point at a single value, or no variant data configured — the role is shown as a placeholder chip and a diagnostic is reported.

Variant field values¶

A need field whose value is written as a variant function (<<...>>), or as a variant data reference (<{ ... }>), is resolved while your project is indexed — not by the preview on its own. So before the first indexing pass a need card shows the raw expression exactly as you wrote it; once the card is hydrated (see Needs), it shows the concrete value the expression resolves to for your configured variant data — the same value a build would produce. See Variants for how these functions are declared.

Variants¶

The if directive¶

The variant role¶

Variant field values¶

The `if` directive¶

The `variant` role¶