👌 Allow collapse/delete/jinja_content directive options to be flags (#…

…1188)

This commit moves the directive option validation of these fields to the directive's `option_spec`,
and also allow the option to be a flag (i.e. have no value, which is then considered to be `True`)

docs/directives/need.rst

@@ -173,7 +173,7 @@ Below is an implementation of variants for need options:
       :id: VA_004
       :status: ['variants' in tags and not collapse]:enabled, disabled
       :tags: variants;support
-      :collapse: true
+      :collapse:
 
       Variants for need options in action
 
@@ -183,7 +183,7 @@ Below is an implementation of variants for need options:
    :id: VA_004
    :status: ['variants' in tags and not collapse]:enabled, disabled
    :tags: variants;support
-   :collapse: true
+   :collapse:
 
    Variants for need options in action
 
@@ -493,7 +493,7 @@ Default: False
 
    .. req:: Collapse is set to True
       :tags: collapse; example
-      :collapse: True
+      :collapse:
 
       Only title and content are shown
 
@@ -507,7 +507,7 @@ Default: False
 
 .. req:: Collapse is set to True
    :tags: collapse; example
-   :collapse: True
+   :collapse:
 
    Only title and content are shown
 
@@ -532,8 +532,8 @@ If you set the option to **False**, you deactivate jinja-parsing for the need's
 
 Allowed values:
 
-* ``true`` or ``yes`` or ``1``
-* ``false`` or ``no`` or ``0``
+* empty, ``true`` or ``yes``
+* ``false`` or ``no``
 
 Default: False
 
@@ -564,7 +564,7 @@ Default: False
           :status: open
           :tags: user;login
           :links: JINJAID126
-          :jinja_content: true
+          :jinja_content:
 
           Nested need with ``:jinja_content:`` option set to ``true``.
           This requirement has tags: **{{ tags | join(', ') }}**.
@@ -578,7 +578,7 @@ Default: False
     .. spec:: First Spec Need
        :id: JINJAID126
        :status: open
-       :jinja_content: true
+       :jinja_content:
 
        Need with ``:jinja_content:`` equal to ``true``.
        This requirement has status: **{{ status }}**.
@@ -598,7 +598,7 @@ Default: False
       :status: open
       :tags: user;login
       :links: JINJAID126
-      :jinja_content: true
+      :jinja_content:
 
       Nested need with ``:jinja_content:`` option set to ``true``.
       This requirement has tags: **{{ tags | join(', ') }}**.
@@ -612,7 +612,7 @@ Default: False
 .. spec:: First Spec Need
    :id: JINJAID126
    :status: open
-   :jinja_content: true
+   :jinja_content:
 
    Need with ``:jinja_content:`` equal to ``true``.
    This requirement has status: **{{ status }}**.

docs/directives/needimport.rst

@@ -17,7 +17,7 @@ You can generate a valid file using the builder :ref:`needs_builder`.
       :version: 1.0
       :tags: imported;external
       :hide:
-      :collapse: True
+      :collapse:
       :filter: "test" in tags
       :template: template.rst
       :pre_template: pre_template.rst

sphinx_needs/api/need.py

@@ -52,8 +52,8 @@ def add_need(
     constraints: None | str | list[str] = None,
     constraints_passed: None | bool = None,
     links_string: None | str | list[str] = None,
-    delete: bool = False,
-    jinja_content: bool = False,
+    delete: None | bool = False,
+    jinja_content: None | bool = False,
     hide: bool = False,
     hide_tags: bool = False,
     hide_status: bool = False,

sphinx_needs/data.py

@@ -68,7 +68,7 @@ class NeedsInfoType(TypedDict, total=False):
     """hide the meta-data information of the need."""
     hide: Required[bool]
     """If true, the need is not rendered."""
-    delete: Required[bool]
+    delete: Required[None | bool]
     """If true, the need is deleted entirely."""
     layout: Required[None | str]
     """Key of the layout, which is used to render the need."""
@@ -115,7 +115,7 @@ class NeedsInfoType(TypedDict, total=False):
     """
 
     # content creation information
-    jinja_content: Required[bool]
+    jinja_content: Required[None | bool]
     template: Required[None | str]
     pre_template: Required[None | str]
     post_template: Required[None | str]

sphinx_needs/defaults.py

@@ -207,14 +207,31 @@
 TITLE_REGEX = r'([^\s]+) as "([^"]+)"'
 
 
+def string_to_boolean(argument: str | None) -> bool | None:
+    """Convert a string (from a directive option) to a boolean.
+
+    The value can be one of case-insensitive "true"/"false" or "yes"/"no",
+    or the empty string also evaluates to True.
+
+    :raises ValueError: If the value is not a valid flag or case-insensitive true/false/yes/no.
+    """
+    if argument is None:
+        return True
+    if argument.upper() in ["", "TRUE", "YES"]:
+        return True
+    if argument.upper() in ["FALSE", "NO"]:
+        return False
+    raise ValueError("not a flag or case-insensitive true/false/yes/no")
+
+
 NEED_DEFAULT_OPTIONS: dict[str, Any] = {
     "id": directives.unchanged_required,
     "status": directives.unchanged_required,
     "tags": directives.unchanged_required,
     "links": directives.unchanged_required,
-    "collapse": directives.unchanged_required,
-    "delete": directives.unchanged,
-    "jinja_content": directives.unchanged,
+    "collapse": string_to_boolean,
+    "delete": string_to_boolean,
+    "jinja_content": string_to_boolean,
     "hide": directives.flag,
     "title_from_content": directives.flag,
     "style": directives.unchanged_required,

sphinx_needs/directives/need.py

@@ -29,7 +29,12 @@
 from sphinx_needs.logging import get_logger
 from sphinx_needs.need_constraints import process_constraints
 from sphinx_needs.nodes import Need
-from sphinx_needs.utils import add_doc, profile, remove_node_from_tree, split_need_id
+from sphinx_needs.utils import (
+    add_doc,
+    profile,
+    remove_node_from_tree,
+    split_need_id,
+)
 
 LOGGER = get_logger(__name__)
 
@@ -87,32 +92,8 @@ def run(self) -> Sequence[nodes.Node]:
         env = self.env
 
         delete_opt = self.options.get("delete")
-        if isinstance(delete_opt, str):
-            if delete_opt.upper() in ["TRUE", 1, "YES"]:
-                delete_opt = True
-            elif delete_opt.upper() in ["FALSE", 0, "NO"]:
-                delete_opt = False
-            else:
-                raise Exception("delete attribute must be true or false")
-
         collapse = self.options.get("collapse")
-        if isinstance(collapse, str):
-            if collapse.upper() in ["TRUE", 1, "YES"]:
-                collapse = True
-            elif collapse.upper() in ["FALSE", 0, "NO"]:
-                collapse = False
-            else:
-                raise Exception("collapse attribute must be true or false")
-
         jinja_content = self.options.get("jinja_content")
-        if isinstance(jinja_content, str):
-            if jinja_content.upper() in ["TRUE", 1, "YES"]:
-                jinja_content = True
-            elif jinja_content.upper() in ["FALSE", 0, "NO"]:
-                jinja_content = False
-            else:
-                raise Exception("jinja_content attribute must be true or false")
-
         hide = "hide" in self.options
 
         id = self.options.get("id")

sphinx_needs/directives/needimport.py

@@ -16,6 +16,7 @@
 from sphinx_needs.config import NEEDS_CONFIG, NeedsSphinxConfig
 from sphinx_needs.data import NeedsInfoType
 from sphinx_needs.debug import measure_time
+from sphinx_needs.defaults import string_to_boolean
 from sphinx_needs.filter_common import filter_single_need
 from sphinx_needs.needsfile import check_needs_file
 from sphinx_needs.utils import add_doc, logger
@@ -34,7 +35,7 @@ class NeedimportDirective(SphinxDirective):
     option_spec = {
         "version": directives.unchanged_required,
         "hide": directives.flag,
-        "collapse": directives.unchanged_required,
+        "collapse": string_to_boolean,
         "filter": directives.unchanged_required,
         "id_prefix": directives.unchanged_required,
         "tags": directives.unchanged_required,

sphinx_needs/utils.py

@@ -264,21 +264,6 @@ def row_col_maker(
     return row_col
 
 
-def rstjinja(app: Sphinx, docname: str, source: list[str]) -> None:
-    """
-    Render our pages as a jinja template for fancy templating goodness.
-    """
-    builder = app.builder
-    # Make sure we're outputting HTML
-    if builder.format != "html":
-        return
-    src = source[0]
-    rendered = builder.templates.render_string(
-        src, app.config.html_context, **NeedsSphinxConfig(app.config).render_context
-    )
-    source[0] = rendered
-
-
 def import_prefix_link_edit(
     needs: dict[str, Any], id_prefix: str, needs_extra_links: list[LinkOptionsType]
 ) -> None: