From 61e3e8e7134fb5d0dc0b0dc9d5aaedd364fce759 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 18 Feb 2025 12:37:18 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Extend=20`c.this=5Fdoc()`=20to=20al?= =?UTF-8?q?l=20directives=20with=20`filter`=20option?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/directives/needextend.rst | 8 ++--- docs/filter.rst | 61 ++++++++++++++++++++++------------ sphinx_needs/filter_common.py | 5 +++ 3 files changed, 47 insertions(+), 27 deletions(-) diff --git a/docs/directives/needextend.rst b/docs/directives/needextend.rst index b2f56651f..02298704a 100644 --- a/docs/directives/needextend.rst +++ b/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 -------------- diff --git a/docs/filter.rst b/docs/filter.rst index 656d1483c..71d961aa9 100644 --- a/docs/filter.rst +++ b/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 `_ + +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 admin@mycompany.com + + .. 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 `_ - -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 admin@mycompany.com - - .. needlist:: - :filter: search("([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)", title) - .. _filter_code: Filter code diff --git a/sphinx_needs/filter_common.py b/sphinx_needs/filter_common.py index eb4143fba..35eea8eec 100644 --- a/sphinx_needs/filter_common.py +++ b/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, )