✨ Add list-needs directive

docs/conf.py

@@ -50,6 +50,8 @@
     ("py:class", "sphinx_needs.debug.T"),
     ("py:class", "sphinx_needs.views._LazyIndexes"),
     ("py:class", "sphinx_needs.config.NeedsSphinxConfig"),
+    ("py:class", "sphinx_needs.nodes.Need"),
+    ("py:class", "sphinx_needs.data.SphinxNeedsData"),
 ]
 
 rst_epilog = """

docs/directives/index.rst

@@ -8,6 +8,7 @@ Directives for creating and modifying needs:
 
    need
    list2need
+   list-needs
    needextend
    needextract
    needimport

docs/directives/list-needs.rst

@@ -0,0 +1,119 @@
+.. _list-needs:
+
+list-needs
+----------
+
+.. versionadded:: 5.2.0
+
+``list-needs`` provides a shorthand notation to create multiple nested needs in one go.
+
+The content of the directive should contain a standard :external+sphinx:ref:`rst-field-lists` block,
+with each item in the list representing a need.
+
+Similar to the :ref:`need directive <need>`, *field name* should start with the need type.
+Proceeding options in the field name can then be specified as white-space delimited; keys with no values (``key``),
+keys with simple (non-whitespace) values (``key=value``), or keys with quoted values (``key="value with space"``).
+
+Allowed field name options are:
+``id``, ``title``, ``status``, ``tags``, ``collapse``, ``delete``, ``hide``, ``layout``, ``style``, ``constraints``,
+:ref:`needs_extra_options`, and :ref:`needs_extra_links`.
+
+Unless specified in the field name parameters, the **title** is taken as the first paragraph of the field content,
+and the **content** is taken as the rest of the field content.
+
+.. need-example:: Simple ``list-needs`` example
+
+    .. list-needs::
+
+        :req id=LIST-1a: Need example title
+
+            Need example on level 1.
+        :req id=LIST-1b:
+            Another Need example with nested needs.
+
+            :spec id=LIST-s2a status=open tags=list-tag1,list-tag2 author="John Doe": 
+                Sub-Need on level 2 with other options set
+            :spec id=LIST-s2b title="Another Sub-Need on level 2.": 
+                With the title given in the parameters.
+
+                :test id=LIST-s3 collapse: Sub-Need on level 3.
+
+                    Content can contain standard *syntax*.
+
+Options
+-------
+
+``defaults``
+~~~~~~~~~~~~
+
+This option allows you to set default values for all needs in the list, it is parsed as a field list similar to the :ref:`need directive options <need>`.
+Defaults will be overridden by any options set in the field name.
+
+.. need-example:: ``defaults`` option
+
+    .. list-needs::
+        :defaults:
+            :status: open
+            :tags: list-tag1,list-tag2
+
+        :req id=LIST-d1: Need level 1
+
+            :spec id=LIST-d2 status=closed: Sub-Need level 2
+
+
+
+``maxdepth``
+~~~~~~~~~~~~
+
+The ``maxdepth`` option allows you to limit the depth of converted field lists.
+
+.. need-example:: ``maxdepth`` option
+
+    .. list-needs::
+        :maxdepth: 1
+
+        :req id=LIST-m1: Need level 1
+
+            :normal: field list
+
+``links-up`` and ``links-down``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``links-up`` and ``links-down`` options allow you to define links between needs in the list,
+according to their structure.
+Both are a comma-delimited list, with each item representing a link type for the corresponding level (starting from 1).
+
+.. need-example:: ``links-up`` and ``links-down`` options
+
+    .. list-needs::
+        :links-down: blocks, triggers
+        :links-up: tests, checks
+
+        :req id=LIST-l1: Need level 1
+
+            :spec id=LIST-l2a: Sub-Need level 2a
+            :spec id=LIST-l2b: Sub-Need level 2b
+
+                :test id=LIST-l3: Sub-Need level 3
+
+``flatten``
+~~~~~~~~~~~
+
+The ``flatten`` option will flatten all nested needs into a single list.
+
+It can be used in combination with the ``links-up`` and ``links-down`` options,
+to define links by structure, without the final representation being nested.
+
+.. need-example:: ``flatten`` option
+
+    .. list-needs::
+        :links-down: blocks, triggers
+        :links-up: tests, checks
+        :flatten:
+
+        :req id=LIST-f1: Need level 1
+
+            :spec id=LIST-f2a: Sub-Need level 2a
+            :spec id=LIST-f2b: Sub-Need level 2b
+
+                :test id=LIST-f3: Sub-Need level 3

sphinx_needs/api/need.py

@@ -465,11 +465,16 @@ def _create_need_node(
     """
     source = env.doc2path(data["docname"]) if data["docname"] else None
 
-    style_classes = ["need", f"need-{data['type'].lower()}"]
-    if data["style"]:
-        style_classes.append(data["style"])
-
-    node_need = Need("", classes=style_classes, ids=[data["id"]], refid=data["id"])
+    node_need = Need(
+        "",
+        classes=[
+            "need",
+            f"need-{data['type'].lower()}",
+            *([data["style"]] if data["style"] else []),
+        ],
+        ids=[data["id"]],
+        refid=data["id"],
+    )
     node_need.source, node_need.line = source, data["lineno"]
 
     if data["hide"]:
@@ -513,14 +518,38 @@ def _create_need_node(
             match_titles=False,
         )
 
-    # Extract plantuml diagrams and store needumls with keys in arch, e.g. need_info['arch']['diagram']
+    add_arch(data, node_need, SphinxNeedsData(env))
+
+    need_parts = find_parts(node_need)
+    update_need_with_parts(env, data, need_parts)
+
+    SphinxNeedsData(env).set_need_node(data["id"], node_need)
+
+    return_nodes.append(node_need)
+
+    if post_content := data.get("post_content"):
+        node = nodes.Element()
+        with _reset_rst_titles(state):
+            state.nested_parse(
+                StringList(post_content.splitlines(), source=source),
+                (data["lineno"] - 1) if data["lineno"] else 0,
+                node,
+                match_titles=True,
+            )
+        return_nodes.extend(node.children)
+
+    return return_nodes
+
+
+def add_arch(data: NeedsInfoType, node_need: Need, needs: SphinxNeedsData) -> None:
+    """Extract plantuml diagrams and store needumls with keys in arch, e.g. ``need_info['arch']['diagram']``"""
     data["arch"] = {}
     node_need_needumls_without_key = []
     node_need_needumls_key_names = []
     for child in node_need.children:
         if isinstance(child, Needuml):
             needuml_id = child.rawsource
-            if needuml := SphinxNeedsData(env).get_or_create_umls().get(needuml_id):
+            if needuml := needs.get_or_create_umls().get(needuml_id):
                 try:
                     key_name = needuml["key"]
                     if key_name:
@@ -541,27 +570,6 @@ def _create_need_node(
     if node_need_needumls_without_key:
         data["arch"]["diagram"] = node_need_needumls_without_key[0]["content"]
 
-    data["parts"] = {}
-    need_parts = find_parts(node_need)
-    update_need_with_parts(env, data, need_parts)
-
-    SphinxNeedsData(env).set_need_node(data["id"], node_need)
-
-    return_nodes.append(node_need)
-
-    if post_content := data.get("post_content"):
-        node = nodes.Element()
-        with _reset_rst_titles(state):
-            state.nested_parse(
-                StringList(post_content.splitlines(), source=source),
-                (data["lineno"] - 1) if data["lineno"] else 0,
-                node,
-                match_titles=True,
-            )
-        return_nodes.extend(node.children)
-
-    return return_nodes
-
 
 def del_need(app: Sphinx, need_id: str) -> None:
     """