🔧 Improve typing/docs of DynamicFunction (#1262)

docs/api.rst

@@ -20,6 +20,9 @@ Configuration
 .. automodule:: sphinx_needs.api.configuration
    :members:
 
+.. autoclass:: sphinx_needs.functions.functions.DynamicFunction
+   :members: __name__,__call__
+
 Need
 ----
 .. automodule:: sphinx_needs.api.need

docs/configuration.rst

@@ -1261,7 +1261,7 @@ needs_functions
 
 Used to register own dynamic functions.
 
-Must be a list of python functions.
+Must be a list of :py:class:`.DynamicFunction`.
 
 Default value: ``[]``
 

docs/dynamic_functions.rst

@@ -18,22 +18,13 @@ dynamic function execution. In this case, the function gets executed with the fo
 This allows you to set row and column specific styles such as, set a row background to red, if a need-status is *failed*.
 
 
-Example
--------
-
-.. code-block:: rst
+.. need-example:: Dynamic function example
 
    .. req:: my test requirement
       :id: df_1
       :status: open
 
-      This need has the id **[[copy("id")]]** and status **[[copy("status")]]**.
-
-.. req:: my test requirement
-   :id: df_1
-   :status: open
-
-   This need has id **[[copy("id")]]** and status **[[copy("status")]]**.
+      This need has id **[[copy("id")]]** and status **[[copy("status")]]**.
 
 Built-in functions
 -------------------
@@ -87,8 +78,8 @@ Develop own functions
 Registration
 ~~~~~~~~~~~~
 
-You must register every dynamic function by using the :ref:`needs_functions` configuration parameter
-inside your **conf.py** file:
+You must register every dynamic function by using the :ref:`needs_functions` configuration parameter,
+inside your **conf.py** file, to add a :py:class:`.DynamicFunction`:
 
 .. code-block:: python
 
@@ -115,61 +106,6 @@ inside your **conf.py** file:
             def setup(app):
                   add_dynamic_function(app, my_function)
 
-Reference function
-~~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-   def test(app, need, needs, *args, **kwargs):
-       """
-       :param app: sphinx app
-       :param need: current need
-       :param needs: dictionary of all needs. Key is the need id
-       :return: str,int,float or list of elements of type str,int,float
-       """
-       # where the magic happens
-       return "awesome"
-
-You can call the defined function via:
-
-.. code-block:: rst
-
-   .. req:: test requirement
-      :status: [[test()]]
-
-The parameters ``app``, ``need`` and ``needs`` are set automatically. You are free to add other parameters, which
-must be of type str, int, float and list.
-
-
-need structure
-~~~~~~~~~~~~~~
-
-.. code-block:: text
-
-   need = {
-      'docname': str: document name,
-      'lineno': int: linenumber,
-      'links_back': list: list of incoming links (see restrictions),
-      'target_node': node: sphinx target node for internal references,
-      'type': str: short name of type,
-      'type_name': str: long name of type,
-      'type_prefix': str: name of type prefix,
-      'type_color': str: type color,
-      'type_style': str: type style,
-      'status': str: status,
-      'tags': list: list of tags,
-      'id': str: id,
-      'links': list: list of outgoing links,
-      'title': str: trimmed title of need,
-      'full_title': str: full title of string,
-      'content': str: unparsed need content,
-      'collapse': bool: true if meta data shall be collapsed,
-      'hide': bool: true if complete need shall be hidden,
-   }
-
-Adding new keywords to need object will be treated as extra_option in need meta area.
-
-
 Restrictions
 ~~~~~~~~~~~~
 

sphinx_needs/directives/need.py

@@ -436,7 +436,7 @@ def format_need_nodes(
         find_and_replace_node_content(node_need, env, need_data)
         for index, attribute in enumerate(node_need.attributes["classes"]):
             node_need.attributes["classes"][index] = check_and_get_content(
-                attribute, need_data, env
+                attribute, need_data, env, node_need
             )
 
         rendered_node = build_need_repr(node_need, need_data, app, docname=fromdocname)

sphinx_needs/directives/needtable.py

@@ -244,7 +244,7 @@ def sort(need: NeedsInfoType) -> Any:
 
         for need_info in filtered_needs:
             style_row = check_and_get_content(
-                current_needtable["style_row"], need_info, env
+                current_needtable["style_row"], need_info, env, node
             )
             style_row = style_row.replace(
                 " ", "_"

sphinx_needs/functions/__init__.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, List
+from typing import List
 
 from sphinx_needs.functions.common import (
     calc_sum,
@@ -9,6 +9,7 @@
     test,
 )
 from sphinx_needs.functions.functions import (  # noqa: F401
+    DynamicFunction,
     FunctionParsingException,
     execute_func,
     find_and_replace_node_content,
@@ -17,8 +18,7 @@
     resolve_variants_options,
 )
 
-# TODO better type signature (Sphinx, NeedsInfoType, Dict[str, NeedsInfoType], *args, **kwargs)
-NEEDS_COMMON_FUNCTIONS: List[Callable[..., Any]] = [
+NEEDS_COMMON_FUNCTIONS: List[DynamicFunction] = [
     test,
     echo,
     copy,

sphinx_needs/functions/common.py

@@ -14,7 +14,7 @@
 
 from sphinx_needs.api.exceptions import NeedsInvalidFilter
 from sphinx_needs.config import NeedsSphinxConfig
-from sphinx_needs.data import NeedsInfoType
+from sphinx_needs.data import NeedsInfoType, NeedsView
 from sphinx_needs.filter_common import filter_needs, filter_single_need
 from sphinx_needs.logging import log_warning
 from sphinx_needs.utils import logger
@@ -23,7 +23,7 @@
 def test(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     *args: Any,
     **kwargs: Any,
 ) -> str:
@@ -50,7 +50,7 @@ def test(
 def echo(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     text: str,
     *args: Any,
     **kwargs: Any,
@@ -74,7 +74,7 @@ def echo(
 def copy(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     option: str,
     need_id: str | None = None,
     lower: bool = False,
@@ -191,7 +191,7 @@ def copy(
 def check_linked_values(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     result: Any,
     search_option: str,
     search_value: Any,
@@ -360,7 +360,7 @@ def check_linked_values(
 def calc_sum(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     option: str,
     filter: str | None = None,
     links_only: bool = False,
@@ -472,7 +472,7 @@ def calc_sum(
 def links_from_content(
     app: Sphinx,
     need: NeedsInfoType,
-    needs: dict[str, NeedsInfoType],
+    needs: NeedsView,
     need_id: str | None = None,
     filter: str | None = None,
 ) -> list[str]: