if

Added in version 8.2.0.

The if directive conditionally includes or excludes content based on variant data evaluated at parse time.

The directive argument is a Python expression evaluated against the var namespace (populated from needs_variant_data). If the expression evaluates to True, the directive body is parsed and included in the document. Otherwise the entire body is skipped. To include one of several branches instead, use choose.

.. if:: var.arch == "arm"

   This paragraph only appears when ``needs_variant_data``
   has ``arch`` set to ``"arm"``.

   .. req:: ARM-specific requirement
      :id: REQ_ARM_001

      This need is only created for the ARM variant.

Usage

Basic conditions

.. if:: var.debug

   Debug-only content here.

.. if:: var.build.optimization > 1

   High-optimization content.

Membership tests

.. if:: "feature_x" in var.build.features

   Feature X documentation.

Nested if directives

if directives can be nested:

.. if:: var.arch == "arm"

   .. if:: var.debug

      ARM debug-specific content.

Content with sections

The body may contain section headers and any valid reStructuredText:

.. if:: var.arch == "arm"

   ARM-specific section
   ~~~~~~~~~~~~~~~~~~~~

   Content under a conditional heading.

Expression context

Only the var namespace is available in the expression. Built-in Python functions (open, import, etc.) are not accessible.

If the expression references a variant key that does not exist, a warning is emitted and the content is skipped.

Supported operators:

  • Comparison: ==, !=, <, >, <=, >=

  • Logical: and, or, not

  • Membership: in

  • Attribute access: var.a.b.c (nested dicts)

Behavior

  • Parse-time evaluation: The condition is evaluated during RST parsing. Unlike Sphinx’s only directive (which defers to doctree resolution), excluded content is never parsed at all.

  • No need data access: Because parsing happens before all needs are collected, need fields and IDs are not available in the expression. Use Filtering needs for need-aware filtering.

  • Incremental builds: If a document is re-read (e.g., because the source changed), all if directives in it are re-evaluated.

  • Parsed on its own: the body does not see where the if stands, so a sphinx-design tab-item in a true if warns that its parent should be a tab-set, even inside one.

Warnings

The directive emits warnings (suppressible via suppress_warnings = ["needs.if"]) when:

  • needs_variant_data is not configured but the directive is used.

  • The expression raises an exception (syntax error, unknown key, etc.).

  • The expression does not return a bool (the result is still used, as its truth value).