✨ Add if directive for variant-conditional content (#1716)

Author: chrisjsewell

docs/directives/if.rst

@@ -0,0 +1,114 @@
+.. _if:
+
+if
+==
+
+.. versionadded:: 8.2.0
+
+The ``if`` directive conditionally includes or excludes content based on
+:ref:`variant data <filter_variant_data>` evaluated at parse time.
+
+The directive argument is a Python expression evaluated against the ``var``
+namespace (populated from :ref:`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.
+
+.. code-block:: rst
+
+   .. 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
+~~~~~~~~~~~~~~~~
+
+.. code-block:: rst
+
+   .. if:: var.debug
+
+      Debug-only content here.
+
+   .. if:: var.build.optimization > 1
+
+      High-optimization content.
+
+Membership tests
+~~~~~~~~~~~~~~~~
+
+.. code-block:: rst
+
+   .. if:: "feature_x" in var.build.features
+
+      Feature X documentation.
+
+Nested if directives
+~~~~~~~~~~~~~~~~~~~~
+
+``if`` directives can be nested:
+
+.. code-block:: rst
+
+   .. if:: var.arch == "arm"
+
+      .. if:: var.debug
+
+         ARM debug-specific content.
+
+Content with sections
+~~~~~~~~~~~~~~~~~~~~~
+
+The body may contain section headers and any valid reStructuredText:
+
+.. code-block:: rst
+
+   .. 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 :ref:`filter` 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.
+
+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.).

docs/directives/index.rst

@@ -13,6 +13,13 @@ Directives for creating and modifying needs:
    needimport
    needservice
 
+Directives for conditional content:
+
+.. toctree::
+   :maxdepth: 1
+
+   if
+
 Directives for visualizing and analyzing needs:
 
 .. toctree::

sphinx_needs/directives/needif.py

@@ -0,0 +1,81 @@
+"""Directive for conditionally including content based on variant data."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import nested_parse_with_titles
+
+from sphinx_needs.config import NeedsSphinxConfig
+from sphinx_needs.logging import get_logger, log_warning
+
+LOGGER = get_logger(__name__)
+
+
+class IfDirective(SphinxDirective):
+    """Conditionally include content based on a variant data expression.
+
+    The directive argument is a Python expression evaluated against the
+    ``var`` namespace (from :confval:`needs_variant_data`).
+    If the expression evaluates to a truthy value, the directive content
+    is parsed and included in the document. Otherwise it is skipped entirely.
+
+    Example::
+
+        .. if:: var.arch == "arm"
+
+           This content only appears when arch is "arm".
+    """
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = True
+
+    def run(self) -> Sequence[nodes.Node]:
+        expression = self.arguments[0]
+        config = NeedsSphinxConfig(self.env.config)
+        var_proxy = config.variant_data_proxy
+
+        if var_proxy is None:
+            log_warning(
+                LOGGER,
+                f"'if' directive used but needs_variant_data is not configured: "
+                f"{expression!r}",
+                "if",
+                location=self.get_location(),
+            )
+            return []
+
+        context: dict[str, object] = {"var": var_proxy, "__builtins__": {}}
+        try:
+            raw_result = eval(expression, context)
+        except Exception as e:
+            log_warning(
+                LOGGER,
+                f"'if' directive expression failed: {expression!r} — {e}",
+                "if",
+                location=self.get_location(),
+            )
+            return []
+
+        if not isinstance(raw_result, bool):
+            log_warning(
+                LOGGER,
+                f"'if' directive expression did not return a bool, "
+                f"got {type(raw_result).__name__}: {raw_result!r} "
+                f"(coercing to bool): {expression!r}",
+                "if",
+                location=self.get_location(),
+            )
+
+        if not raw_result:
+            return []
+
+        # Parse the content into a container node
+        node = nodes.container()
+        node.document = self.state.document
+        nested_parse_with_titles(self.state, self.content, node, self.content_offset)
+        return node.children

sphinx_needs/logging.py

@@ -29,6 +29,7 @@ def get_logger(name: str) -> SphinxLoggerAdapter:
     "filter_func",
     "filter",
     "github",
+    "if",
     "import_need",
     "json_load",
     "layout",
@@ -74,6 +75,7 @@ def get_logger(name: str) -> SphinxLoggerAdapter:
     "filter_func": "Error loading needs filter function",
     "filter": "Error processing needs filter",
     "github": "Error in processing GitHub service directive",
+    "if": "Error in processing if directive",
     "import_need": "Failed to import a need",
     "layout": "Error occurred during layout rendering of a need",
     "link_condition_failed": "Link condition not satisfied by targeted need",

sphinx_needs/needs.py

@@ -77,6 +77,7 @@
     NeedganttDirective,
     process_needgantt,
 )
+from sphinx_needs.directives.needif import IfDirective
 from sphinx_needs.directives.needimport import Needimport, NeedimportDirective
 from sphinx_needs.directives.needlist import (
     Needlist,
@@ -270,6 +271,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_directive("needextend", NeedextendDirective)
     app.add_directive("needreport", NeedReportDirective)
     app.add_directive("needuml", NeedumlDirective)
+    app.add_directive("if", IfDirective)
     app.add_directive("needarch", NeedarchDirective)
     app.add_directive("list2need", List2NeedDirective)
 

tests/doc_test/doc_if_directive/conf.py

@@ -0,0 +1,20 @@
+project = "needs_if_test"
+version = "0.1.0"
+extensions = ["sphinx_needs"]
+
+suppress_warnings = ["epub.unknown_project_files"]
+
+needs_types = [
+    {
+        "directive": "req",
+        "title": "Requirement",
+        "prefix": "REQ_",
+        "color": "#BFD8D2",
+    },
+]
+
+needs_variant_data = {
+    "arch": "abc",
+    "debug": True,
+    "build": {"opt": 2, "features": ["f1", "f2"]},
+}

tests/doc_test/doc_if_directive/index.rst

@@ -0,0 +1,94 @@
+IF Directive Test
+=================
+
+True condition
+--------------
+
+.. if:: var.arch == "abc"
+
+   INCLUDED_ARCH_ABC
+
+False condition
+---------------
+
+.. if:: var.arch == "xyz"
+
+   EXCLUDED_ARCH_XYZ
+
+Boolean truthiness
+------------------
+
+.. if:: var.debug
+
+   INCLUDED_DEBUG_TRUE
+
+.. if:: not var.debug
+
+   EXCLUDED_DEBUG_FALSE
+
+Nested access
+-------------
+
+.. if:: var.build.opt > 1
+
+   INCLUDED_BUILD_OPT
+
+.. if:: var.build.opt > 99
+
+   EXCLUDED_BUILD_OPT_HIGH
+
+Membership test
+---------------
+
+.. if:: "f1" in var.build.features
+
+   INCLUDED_FEATURE_F1
+
+.. if:: "missing" in var.build.features
+
+   EXCLUDED_FEATURE_MISSING
+
+Nested if directives
+--------------------
+
+.. if:: var.debug
+
+   OUTER_IF_CONTENT
+
+   .. if:: var.arch == "abc"
+
+      NESTED_IF_CONTENT
+
+Header inside if
+-----------------
+
+.. if:: var.arch == "abc"
+
+   Conditional section
+   ~~~~~~~~~~~~~~~~~~~
+
+   INCLUDED_SECTION_CONTENT
+
+.. if:: var.arch == "xyz"
+
+   Skipped section
+   ~~~~~~~~~~~~~~~
+
+   EXCLUDED_SECTION_CONTENT
+
+Needs inside if
+---------------
+
+.. if:: var.arch == "abc"
+
+   .. req:: A conditional requirement
+      :id: REQ_CONDITIONAL
+
+      This requirement only exists when arch is abc.
+
+.. if:: var.arch == "xyz"
+
+   .. req:: A skipped requirement
+      :id: REQ_SKIPPED
+
+      This requirement should not exist.

tests/doc_test/doc_if_no_variant/conf.py

@@ -0,0 +1,16 @@
+project = "needs_if_no_variant"
+version = "0.1.0"
+extensions = ["sphinx_needs"]
+
+suppress_warnings = ["epub.unknown_project_files"]
+
+needs_types = [
+    {
+        "directive": "req",
+        "title": "Requirement",
+        "prefix": "REQ_",
+        "color": "#BFD8D2",
+    },
+]
+
+# No needs_variant_data configured

tests/doc_test/doc_if_no_variant/index.rst

@@ -0,0 +1,6 @@
+IF without variant data
+=======================
+
+.. if:: var.arch == "abc"
+
+   SHOULD_NOT_APPEAR