🔧 Centralise allowed variant core need fields (#1424)

Similar to #1388 for `needs_variant_options`

---------

Co-authored-by: Marco Heinemann <[email protected]>

Author: chrisjsewell

docs/configuration.rst

@@ -2249,8 +2249,14 @@ Default: ``[]``
 
 .. note::
 
-   1. You must ensure the options in ``needs_variant_options`` are either default need options or specified in
-      :ref:`extra options <needs_extra_options>` or :ref:`extra links <needs_extra_links>`.
+   1. You must ensure the options in ``needs_variant_options`` are specified in:
+      - ``status``
+      - ``tags``
+      - ``layout``
+      - ``style``
+      - ``constraints``
+      - :ref:`extra options <needs_extra_options>`
+      - :ref:`extra links <needs_extra_links>`.
    2. By default, if ``needs_variant_options`` is empty, we deactivate variants handling for need options.
 
 .. _needs_render_context:

sphinx_needs/data.py

@@ -68,6 +68,8 @@ class CoreFieldParameters(TypedDict):
     """Whether field can be modified by needextend (False if not present)."""
     allow_df: NotRequired[bool]
     """Whether dynamic functions are allowed for this field (False if not present)."""
+    allow_variants: NotRequired[bool]
+    """Whether variant options are allowed for this field (False if not present)."""
     deprecate_df: NotRequired[bool]
     """Whether dynamic functions are deprecated for this field (False if not present)."""
     show_in_layout: NotRequired[bool]
@@ -112,6 +114,7 @@ class CoreFieldParameters(TypedDict):
         "show_in_layout": True,
         "allow_default": "str",
         "allow_df": True,
+        "allow_variants": True,
         "allow_extend": True,
     },
     "tags": {
@@ -120,6 +123,7 @@ class CoreFieldParameters(TypedDict):
         "show_in_layout": True,
         "allow_default": "str_list",
         "allow_df": True,
+        "allow_variants": True,
         "allow_extend": True,
     },
     "collapse": {
@@ -142,6 +146,7 @@ class CoreFieldParameters(TypedDict):
         "show_in_layout": True,
         "allow_default": "str",
         "allow_df": True,
+        "allow_variants": True,
         "exclude_external": True,
     },
     "style": {
@@ -151,6 +156,7 @@ class CoreFieldParameters(TypedDict):
         "exclude_external": True,
         "allow_default": "str",
         "allow_df": True,
+        "allow_variants": True,
         "allow_extend": True,
     },
     "arch": {
@@ -313,6 +319,7 @@ class CoreFieldParameters(TypedDict):
         "schema": {"type": "array", "items": {"type": "string"}, "default": []},
         "allow_default": "str_list",
         "allow_df": True,
+        "allow_variants": True,
         "allow_extend": True,
     },
     "constraints_results": {

sphinx_needs/needs.py

@@ -720,12 +720,15 @@ def check_configuration(app: Sphinx, config: Config) -> None:
                 f"Variant filter value: {value} from needs_variants {external_variants} is not a string."
             )
 
+    allowed_internal_variants = {
+        k for k, v in NeedsCoreFields.items() if v.get("allow_variants")
+    }
     for option in external_variant_options:
         # Check variant option is added in either extra options or extra links or NEED_DEFAULT_OPTIONS
         if (
             option not in extra_options
             and option not in link_types
-            and option not in NEED_DEFAULT_OPTIONS
+            and option not in allowed_internal_variants
         ):
             raise NeedsConfigException(
                 f"Variant option `{option}` is not added in either extra options or extra links. "