✨ Allow configuring description of extra option

docs/configuration.rst

@@ -256,6 +256,20 @@ And use it like:
    .. needlist::
       :filter: "filter_me" in another_option
 
+.. versionadded:: 4.1.0
+
+    Values in the list can also be dictionaries, allowing for setting a description of an option
+    that will be output in the schema of the :ref:`needs.json <needs_builder_format>`.
+
+    For example:
+
+    .. code-block:: python
+
+       needs_extra_options = [
+           "my_extra_option",
+           {"name": "my_other_option", "description": "This is a description of the option"}
+       ]
+
 .. _needs_global_options:
 
 needs_global_options

sphinx_needs/config.py

@@ -228,6 +228,14 @@ class NeedType(TypedDict):
     """The default node style to use in diagrams (default: "node")."""
 
 
+class NeedExtraOption(TypedDict):
+    """Defines an extra option for needs"""
+
+    name: str
+    description: NotRequired[str]
+    """A description of the option."""
+
+
 @dataclass
 class NeedsSphinxConfig:
     """A wrapper around the Sphinx configuration,
@@ -407,7 +415,7 @@ def get_default(cls, name: str) -> Any:
         default=30, metadata={"rebuild": "html", "types": (int,)}
     )
     """Maximum length of the title in the need role output."""
-    _extra_options: list[str] = field(
+    _extra_options: list[str | NeedExtraOption] = field(
         default_factory=list, metadata={"rebuild": "html", "types": (list,)}
     )
     """List of extra options for needs, that get added as directive options and need fields."""

sphinx_needs/needs.py

@@ -417,9 +417,18 @@ def load_config(app: Sphinx, *_args: Any) -> None:
         )
 
     for option in needs_config._extra_options:
-        _NEEDS_CONFIG.add_extra_option(
-            option, "Added by needs_extra_options config", override=True
-        )
+        description = "Added by needs_extra_options config"
+        if isinstance(option, str):
+            name = option
+        elif isinstance(option, dict):
+            name = option["name"]
+            description = option.get("description", description)
+        else:
+            raise NeedsConfigException(
+                f"Extra option {option} is not a string or dict."
+            )
+
+        _NEEDS_CONFIG.add_extra_option(name, description, override=True)
 
     # ensure options for ``needgantt`` functionality are added to the extra options
     for option in (needs_config.duration_option, needs_config.completion_option):