From c75d579618b5c96ba273d07ae47b4321e4346a84 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 18 Feb 2025 23:55:44 +0100 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=94=A7=20Deprecate=20use=20of=20dynam?= =?UTF-8?q?ic=20functions=20in=20type=20fields?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It is unintended and unlikely the dynamic functions would have been used in there fields, but just in case we issue a warning of the deprecation, so that we can remove them in the future fields affected: `type`, `type_name`, `type_prefix`, `type_color`, `type_style`. --- Note, there are still maybe some outstanding questions about where dynamic functions should be processed: - should they be processed fo the need title? - should they be processed at all for needs coming from external and/or needimport `needs.json`? --- docs/dynamic_functions.rst | 10 ++++++++++ sphinx_needs/data.py | 12 +++++++----- sphinx_needs/functions/functions.py | 19 ++++++++++++++++++- 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/dynamic_functions.rst b/docs/dynamic_functions.rst index 4d2c280b4..cb650aae9 100644 --- a/docs/dynamic_functions.rst +++ b/docs/dynamic_functions.rst @@ -24,6 +24,16 @@ To refer to a dynamic function, you can use the following syntax: This need has id :ndf:`copy("id")` and status :ndf:`copy("status")`. +Dynamic functions can be used for the directive title, and the following directive options: + +- ``status`` +- ``tags`` +- ``style`` +- ``constraints`` +- :ref:`needs_extra_options` +- :ref:`needs_extra_links` +- :ref:`needs_global_options` + .. deprecated:: 3.1.0 The :ref:`ndf` role replaces the use of the ``[[...]]`` syntax in need content. diff --git a/sphinx_needs/data.py b/sphinx_needs/data.py index 44df692a3..857bb6094 100644 --- a/sphinx_needs/data.py +++ b/sphinx_needs/data.py @@ -64,6 +64,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).""" + deprecate_df: NotRequired[bool] + """Whether dynamic functions are deprecated for this field (False if not present).""" show_in_layout: NotRequired[bool] """Whether to show the field in the rendered layout of the need by default (False if not present).""" exclude_external: NotRequired[bool] @@ -170,14 +172,14 @@ class CoreFieldParameters(TypedDict): "type": { "description": "Type of the need.", "schema": {"type": "string", "default": ""}, - "allow_df": True, + "deprecate_df": True, }, "type_name": { "description": "Name of the type.", "schema": {"type": "string", "default": ""}, "exclude_external": True, "exclude_import": True, - "allow_df": True, + "deprecate_df": True, }, "type_prefix": { "description": "Prefix of the type.", @@ -185,7 +187,7 @@ class CoreFieldParameters(TypedDict): "exclude_json": True, "exclude_external": True, "exclude_import": True, - "allow_df": True, + "deprecate_df": True, }, "type_color": { "description": "Hexadecimal color code of the type.", @@ -193,7 +195,7 @@ class CoreFieldParameters(TypedDict): "exclude_json": True, "exclude_external": True, "exclude_import": True, - "allow_df": True, + "deprecate_df": True, }, "type_style": { "description": "Style of the type.", @@ -201,7 +203,7 @@ class CoreFieldParameters(TypedDict): "exclude_json": True, "exclude_external": True, "exclude_import": True, - "allow_df": True, + "deprecate_df": True, }, "is_modified": { "description": "Whether the need was modified by needextend.", diff --git a/sphinx_needs/functions/functions.py b/sphinx_needs/functions/functions.py index 892cc6a6e..a81394c36 100644 --- a/sphinx_needs/functions/functions.py +++ b/sphinx_needs/functions/functions.py @@ -237,11 +237,18 @@ def resolve_dynamic_values(needs: NeedsMutable, app: Sphinx) -> None: config = NeedsSphinxConfig(app.config) allowed_fields: set[str] = { - *(k for k, v in NeedsCoreFields.items() if v.get("allow_df", False)), + *( + k + for k, v in NeedsCoreFields.items() + if v.get("allow_df", False) or v.get("deprecate_df", False) + ), *config.extra_options, *(link["option"] for link in config.extra_links), *config.global_options, } + deprecated_fields: set[str] = { + *(k for k, v in NeedsCoreFields.items() if v.get("deprecate_df", False)), + } for need in needs.values(): for need_option in need: @@ -267,6 +274,16 @@ def resolve_dynamic_values(needs: NeedsMutable, app: Sphinx) -> None: if func_call is None: continue + if need_option in deprecated_fields: + log_warning( + logger, + f"Usage of dynamic functions is deprecated in field {need_option!r}, found in need {need['id']!r}", + "deprecated", + location=(need["docname"], need["lineno"]) + if need.get("docname") + else None, + ) + # Replace original function string with return value of function call if func_return is None: need[need_option] = need[need_option].replace( From 10105071c9e54b9b479f911c2f359096fb23e75b Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Thu, 20 Feb 2025 11:25:33 +0100 Subject: [PATCH 2/2] Update dynamic_functions.rst --- docs/dynamic_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dynamic_functions.rst b/docs/dynamic_functions.rst index cb650aae9..a621c9468 100644 --- a/docs/dynamic_functions.rst +++ b/docs/dynamic_functions.rst @@ -24,7 +24,7 @@ To refer to a dynamic function, you can use the following syntax: This need has id :ndf:`copy("id")` and status :ndf:`copy("status")`. -Dynamic functions can be used for the directive title, and the following directive options: +Dynamic functions can be used for the following directive options: - ``status`` - ``tags``