✨ Extend c.this_doc() to all directives with filter option (#1405)

extending #1393

Author: chrisjsewell

docs/directives/needextend.rst

@@ -95,13 +95,11 @@ Default: false
 Extending needs in current page
 -------------------------------
 
-.. versionadded:: 4.3.0
+.. versionadded:: 5.0.0
 
-Additionally, to common :ref:`filter_string` variables, the ``c.this_doc()`` function is made available,
+The ``c.this_doc()`` function is made available,
 to filter for needs only in the same document as the ``needextend``.
 
-You can use ``needextend``'s filter string to set default option values for a group of needs.
-
 The following example would set the status of all needs in the current document,
 which do not have the status set explicitly, to ``open``.
 
@@ -110,7 +108,7 @@ which do not have the status set explicitly, to ``open``.
    .. needextend:: c.this_doc() and status is None
       :status: open
 
-See also: :ref:`needs_global_options` for setting a default option value for all needs.
+See also, :ref:`filter_current_page` and :ref:`needs_global_options` for setting a default option value for all needs.
 
 Changing links
 --------------

docs/filter.rst

@@ -188,6 +188,45 @@ If it is invalid or returns False, the related need is not taken into account fo
       .. needlist::
          :filter: "filter_example" in tags and (("B" in tags or ("spec" == type and "closed" == status)) or "test" == type)
 
+.. _filter_current_page:
+
+Filtering for needs on the current page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.0.0
+
+Additionally, to common :ref:`filter_string` variables,
+the ``c.this_doc()`` function is for most directives,
+to filter for needs only in the same document as the directive.
+
+.. need-example::
+
+   .. needtable::
+      :filter: c.this_doc()
+      :style: datatables
+
+.. _re_search:
+
+search
+~~~~~~
+
+search(pattern, variable) is based on
+`Pythons re.search() function <https://docs.python.org/3/library/re.html#re.search>`_
+
+The first parameter must be a regular expression pattern.
+The second parameter should be one of the above variables(status, id, content, ..)
+
+.. dropdown:: Show example
+
+   This example uses a regular expressions to find all needs with an e-mail address in title.
+
+   .. need-example::
+
+      .. req:: Set admin e-mail to [email protected]
+
+      .. needlist::
+         :filter: search("([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)", title)
+
 .. _filter_string_performance:
 
 Filter string performance
@@ -224,28 +263,6 @@ To debug which filters are being used across your project and their run times, y
    This is deprecated and will be removed in a future version.
    Instead use the above :ref:`needs_debug_filters` configuration option.
 
-.. _re_search:
-
-search
-~~~~~~
-
-search(pattern, variable) is based on
-`Pythons re.search() function <https://docs.python.org/3/library/re.html#re.search>`_
-
-The first parameter must be a regular expression pattern.
-The second parameter should be one of the above variables(status, id, content, ..)
-
-.. dropdown:: Show example
-
-   This example uses a regular expressions to find all needs with an e-mail address in title.
-
-   .. need-example::
-
-      .. req:: Set admin e-mail to [email protected]
-
-      .. needlist::
-         :filter: search("([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)", title)
-
 .. _filter_code:
 
 Filter code

sphinx_needs/filter_common.py

@@ -180,6 +180,7 @@ def process_filters(
             needs_config,
             filter_data["filter"],
             location=location,
+            origin_docname=filter_data["docname"],
         )
     else:
         # The filter results may be dirty, as it may continue manipulated needs.
@@ -413,6 +414,7 @@ def filter_needs_view(
     location: tuple[str, int | None] | nodes.Node | None = None,
     append_warning: str = "",
     strict_eval: bool = False,
+    origin_docname: str | None = None,
 ) -> list[NeedsInfoType]:
     if not filter_string:
         return list(needs.values())
@@ -440,6 +442,7 @@ def filter_needs_view(
         current_need,
         location=location,
         append_warning=append_warning,
+        origin_docname=origin_docname,
     )
 
 
@@ -452,6 +455,7 @@ def filter_needs_parts(
     location: tuple[str, int | None] | nodes.Node | None = None,
     append_warning: str = "",
     strict_eval: bool = False,
+    origin_docname: str | None = None,
 ) -> list[NeedsInfoType]:
     if not filter_string:
         return list(needs)
@@ -479,6 +483,7 @@ def filter_needs_parts(
         current_need,
         location=location,
         append_warning=append_warning,
+        origin_docname=origin_docname,
     )