From ac4165c84011414d3e14b4224e51ed8a50d88581 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Wed, 2 Oct 2024 13:02:07 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20Remove=20deprecated=20`needfilte?= =?UTF-8?q?r`=20directive=20(#1308)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This has been deprecated since v0.2.0, so high time to remove the code --- docs/configuration.rst | 4 +- docs/filter.rst | 2 +- sphinx_needs/data.py | 13 - sphinx_needs/directives/needfilter.py | 303 ------------------- sphinx_needs/needs.py | 10 - tests/doc_test/doc_github_issue_21/index.rst | 6 +- tests/doc_test/doc_needsfile/index.rst | 2 +- tests/doc_test/doc_style_blank/index.rst | 2 +- tests/doc_test/doc_style_custom/index.rst | 2 +- tests/doc_test/doc_style_modern/index.rst | 2 +- tests/doc_test/doc_style_unknown/index.rst | 2 +- tests/doc_test/filter_doc/filter_all.rst | 4 +- tests/doc_test/filter_doc/filter_search.rst | 4 +- tests/doc_test/filter_doc/filter_tags_or.rst | 2 +- tests/doc_test/filter_doc/index.rst | 8 +- 15 files changed, 20 insertions(+), 346 deletions(-) delete mode 100644 sphinx_needs/directives/needfilter.py diff --git a/docs/configuration.rst b/docs/configuration.rst index 75fe7fff0..72500a19d 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -179,7 +179,7 @@ And use it like: Some content - .. needfilter:: + .. needlist:: :filter: "filter_me" in another_option **Result** @@ -192,7 +192,7 @@ And use it like: Some content - .. needfilter:: + .. needlist:: :filter: "filter_me" in another_option .. _needs_global_options: diff --git a/docs/filter.rst b/docs/filter.rst index b142950dc..3eb084f76 100644 --- a/docs/filter.rst +++ b/docs/filter.rst @@ -185,7 +185,7 @@ If it is invalid or returns False, the related need is not taken into account fo :tags: filter_example :hide: - .. needfilter:: + .. needlist:: :filter: "filter_example" in tags and (("B" in tags or ("spec" == type and "closed" == status)) or "test" == type) .. _filter_string_performance: diff --git a/sphinx_needs/data.py b/sphinx_needs/data.py index 2d0704bc1..0ba3e6562 100644 --- a/sphinx_needs/data.py +++ b/sphinx_needs/data.py @@ -559,19 +559,6 @@ class NeedsExtractType(NeedsFilteredBaseType): filter_arg: None | str -class _NeedsFilterType(NeedsFilteredBaseType): - """Data to present (filtered) needs inside a list, table or diagram - - .. deprecated:: 0.2.0 - """ - - show_tags: bool - show_status: bool - show_filters: bool - show_legend: bool - layout: Literal["list", "table", "diagram"] - - class GraphvizStyleType(TypedDict, total=False): """Defines a graphviz style""" diff --git a/sphinx_needs/directives/needfilter.py b/sphinx_needs/directives/needfilter.py deleted file mode 100644 index 82376d147..000000000 --- a/sphinx_needs/directives/needfilter.py +++ /dev/null @@ -1,303 +0,0 @@ -from __future__ import annotations - -import os -from contextlib import suppress -from typing import Sequence -from urllib.parse import urlparse - -from docutils import nodes -from docutils.parsers.rst import directives -from jinja2 import Template -from sphinx.application import Sphinx -from sphinx.errors import NoUri - -from sphinx_needs.config import NeedsSphinxConfig -from sphinx_needs.data import SphinxNeedsData, _NeedsFilterType -from sphinx_needs.diagrams_common import create_legend -from sphinx_needs.directives.utils import no_needs_found_paragraph -from sphinx_needs.filter_common import FilterBase, process_filters -from sphinx_needs.utils import add_doc, remove_node_from_tree, row_col_maker - - -class Needfilter(nodes.General, nodes.Element): - pass - - -class NeedfilterDirective(FilterBase): - """ - Directive to filter needs and present them inside a list, table or diagram. - - .. deprecated:: 0.2.0 - Use needlist, needtable or needdiagram instead - """ - - @staticmethod - def layout(argument: str) -> str: - return directives.choice(argument, ("list", "table", "diagram")) # type: ignore - - option_spec = { - "show_status": directives.flag, - "show_tags": directives.flag, - "show_filters": directives.flag, - "show_links": directives.flag, - "show_legend": directives.flag, - "layout": layout, - } - - # Update the options_spec with values defined in the FilterBase class - option_spec.update(FilterBase.base_option_spec) - - def run(self) -> Sequence[nodes.Node]: - env = self.env - - targetid = "needfilter-{docname}-{id}".format( - docname=env.docname, id=env.new_serialno("needfilter") - ) - targetnode = nodes.target("", "", ids=[targetid]) - - attributes: _NeedsFilterType = { - "docname": env.docname, - "lineno": self.lineno, - "target_id": targetid, - "show_tags": "show_tags" in self.options, - "show_status": "show_status" in self.options, - "show_filters": "show_filters" in self.options, - "show_legend": "show_legend" in self.options, - "layout": self.options.get("layout", "list"), - **self.collect_filter_attributes(), - } - node = Needfilter("", **attributes) - self.set_source_info(node) - - add_doc(env, env.docname) - - return [targetnode, node] - - -def process_needfilters( - app: Sphinx, - doctree: nodes.document, - fromdocname: str, - found_nodes: list[nodes.Element], -) -> None: - # Replace all needlist nodes with a list of the collected needs. - # Augment each need with a backlink to the original location. - builder = app.builder - env = app.env - needs_config = NeedsSphinxConfig(env.config) - all_needs = SphinxNeedsData(env).get_needs_view() - - # NEEDFILTER - # for node in doctree.findall(Needfilter): - for node in found_nodes: - if not needs_config.include_needs: - remove_node_from_tree(node) - continue - - current_needfilter: _NeedsFilterType = node.attributes - - content: nodes.Element | list[nodes.Element] - if current_needfilter["layout"] == "list": - content = [] - - elif current_needfilter["layout"] == "diagram": - content = [] - try: - if "sphinxcontrib.plantuml" not in app.config.extensions: - raise ImportError - from sphinxcontrib.plantuml import plantuml - except ImportError: - error_node = nodes.error() - para_node = nodes.paragraph() - text = nodes.Text("PlantUML is not available!") - para_node += text - error_node.append(para_node) - node.replace_self(error_node) - continue - - plantuml_block_text = ".. plantuml::\n" "\n" " @startuml" " @enduml" - puml_node = plantuml(plantuml_block_text) - - # Add source origin - puml_node.line = current_needfilter["lineno"] - puml_node.source = env.doc2path(current_needfilter["docname"]) - - puml_node["uml"] = "@startuml\n" - puml_connections = "" - - elif current_needfilter["layout"] == "table": - content = nodes.table() - tgroup = nodes.tgroup() - id_colspec = nodes.colspec(colwidth=5) - title_colspec = nodes.colspec(colwidth=15) - type_colspec = nodes.colspec(colwidth=5) - status_colspec = nodes.colspec(colwidth=5) - links_colspec = nodes.colspec(colwidth=5) - tags_colspec = nodes.colspec(colwidth=5) - tgroup += [ - id_colspec, - title_colspec, - type_colspec, - status_colspec, - links_colspec, - tags_colspec, - ] - tgroup += nodes.thead( - "", - nodes.row( - "", - nodes.entry("", nodes.paragraph("", "ID")), - nodes.entry("", nodes.paragraph("", "Title")), - nodes.entry("", nodes.paragraph("", "Type")), - nodes.entry("", nodes.paragraph("", "Status")), - nodes.entry("", nodes.paragraph("", "Links")), - nodes.entry("", nodes.paragraph("", "Tags")), - ), - ) - tbody = nodes.tbody() - tgroup += tbody - content += tgroup - - found_needs = process_filters( - app, - all_needs, - current_needfilter, - origin="needfilter", - location=node, - ) - - line_block = nodes.line_block() - for need_info in found_needs: - target_id = need_info["target_id"] - - if current_needfilter["layout"] == "list": - line_node = nodes.line() - description = "{}: {}".format(need_info["id"], need_info["title"]) - - if current_needfilter["show_status"] and need_info["status"]: - description += " ({})".format(need_info["status"]) - - if current_needfilter["show_tags"] and need_info["tags"]: - description += " [{}]".format("; ".join(need_info["tags"])) - - title = nodes.Text(description) - - # Create a reference - if need_info["hide"]: - line_node += title - elif _docname := need_info["docname"]: - ref = nodes.reference("", "") - ref["refdocname"] = _docname - ref["refuri"] = builder.get_relative_uri(fromdocname, _docname) - ref["refuri"] += "#" + target_id - ref.append(title) - line_node += ref - - line_block.append(line_node) - elif current_needfilter["layout"] == "table": - row = nodes.row() - row += row_col_maker( - app, fromdocname, all_needs, need_info, "id", make_ref=True - ) - row += row_col_maker(app, fromdocname, all_needs, need_info, "title") - row += row_col_maker( - app, fromdocname, all_needs, need_info, "type_name" - ) - row += row_col_maker(app, fromdocname, all_needs, need_info, "status") - row += row_col_maker( - app, fromdocname, all_needs, need_info, "links", ref_lookup=True - ) - row += row_col_maker(app, fromdocname, all_needs, need_info, "tags") - tbody += row - elif current_needfilter["layout"] == "diagram": - # Link calculation - # All links we can get from docutils functions will be relative. - # But the generated link in the svg will be relative to the svg-file location - # (e.g. server.com/docs/_images/sqwxo499cnq329439dfjne.svg) - # and not to current documentation. Therefore we need to add ../ to get out of the image folder. - link = "" - with suppress(NoUri): - # Gets mostly called during latex generation - if _docname := need_info["docname"]: - link = ( - "../" - + builder.get_target_uri(_docname) - + "?highlight={}".format(urlparse(need_info["title"])) - + "#" - + target_id - ) - - diagram_template = Template(needs_config.diagram_template) - node_text = diagram_template.render( - **need_info, **needs_config.render_context - ) - - puml_node["uml"] += ( - '{style} "{node_text}" as {id} [[{link}]] {color}\n'.format( - id=need_info["id"], - node_text=node_text, - link=link, - color=need_info["type_color"], - style=need_info["type_style"], - ) - ) - for link in need_info["links"]: - puml_connections += "{id} --> {link}\n".format( - id=need_info["id"], link=link - ) - - if current_needfilter["layout"] == "list": - content.append(line_block) - - if current_needfilter["layout"] == "diagram": - puml_node["uml"] += puml_connections - - # Create a legend - - if current_needfilter["show_legend"]: - puml_node["uml"] += create_legend(needs_config.types) - puml_node["uml"] += "@enduml" - puml_node["incdir"] = os.path.dirname(current_needfilter["docname"]) - puml_node["filename"] = os.path.split(current_needfilter["docname"])[ - 1 - ] # Needed for plantuml >= 0.9 - content.append(puml_node) - - if len(content) == 0: - content.append( - no_needs_found_paragraph(current_needfilter.get("filter_warning")) - ) - if current_needfilter["show_filters"]: - para_node = nodes.paragraph() - filter_text = "Used filter:" - filter_text += ( - " status({})".format(" OR ".join(current_needfilter["status"])) - if len(current_needfilter["status"]) > 0 - else "" - ) - if ( - len(current_needfilter["status"]) > 0 - and len(current_needfilter["tags"]) > 0 - ): - filter_text += " AND " - filter_text += ( - " tags({})".format(" OR ".join(current_needfilter["tags"])) - if len(current_needfilter["tags"]) > 0 - else "" - ) - if ( - len(current_needfilter["status"]) > 0 - or len(current_needfilter["tags"]) > 0 - ) and len(current_needfilter["types"]) > 0: - filter_text += " AND " - filter_text += ( - " types({})".format(" OR ".join(current_needfilter["types"])) - if len(current_needfilter["types"]) > 0 - else "" - ) - - filter_node = nodes.emphasis(filter_text, filter_text) - para_node += filter_node - content.append(para_node) - - node.replace_self(content) diff --git a/sphinx_needs/needs.py b/sphinx_needs/needs.py index 65a301503..09e56951f 100644 --- a/sphinx_needs/needs.py +++ b/sphinx_needs/needs.py @@ -46,11 +46,6 @@ NeedextractDirective, process_needextract, ) -from sphinx_needs.directives.needfilter import ( - Needfilter, - NeedfilterDirective, - process_needfilters, -) from sphinx_needs.directives.needflow import ( NeedflowDirective, NeedflowGraphiz, @@ -126,7 +121,6 @@ NODE_TYPES: _NODE_TYPES_T = { Needbar: process_needbar, # Needextract: process_needextract, - Needfilter: process_needfilters, Needlist: process_needlist, Needtable: process_needtables, NeedflowPlantuml: process_needflow_plantuml, @@ -163,9 +157,6 @@ def setup(app: Sphinx) -> dict[str, Any]: app.add_node( Need, html=(html_visit, html_depart), latex=(latex_visit, latex_depart) ) - app.add_node( - Needfilter, - ) app.add_node(Needbar) app.add_node(Needimport) app.add_node(Needlist) @@ -192,7 +183,6 @@ def setup(app: Sphinx) -> dict[str, Any]: # Define directives app.add_directive("needbar", NeedbarDirective) - app.add_directive("needfilter", NeedfilterDirective) app.add_directive("needlist", NeedlistDirective) app.add_directive("needtable", NeedtableDirective) app.add_directive("needflow", NeedflowDirective) diff --git a/tests/doc_test/doc_github_issue_21/index.rst b/tests/doc_test/doc_github_issue_21/index.rst index 475670802..7163729ae 100644 --- a/tests/doc_test/doc_github_issue_21/index.rst +++ b/tests/doc_test/doc_github_issue_21/index.rst @@ -35,13 +35,13 @@ As :need:IMPL_01 shows, the linked :need:OWN_ID_123 is realisable. **Filter result as list** -.. needfilter:: +.. needlist:: :tags: test :show_filters: **Filter result as table** - .. needfilter:: + .. needlist:: :tags: test :status: implemented :show_filters: @@ -49,5 +49,5 @@ As :need:IMPL_01 shows, the linked :need:OWN_ID_123 is realisable. **Filter result as diagram** -.. needfilter:: +.. needlist:: :layout: diagram \ No newline at end of file diff --git a/tests/doc_test/doc_needsfile/index.rst b/tests/doc_test/doc_needsfile/index.rst index cd3a0e0bf..eb4c71f6b 100644 --- a/tests/doc_test/doc_needsfile/index.rst +++ b/tests/doc_test/doc_needsfile/index.rst @@ -11,5 +11,5 @@ TEST DOCUMENT .. story:: A story :tags: 1 -.. needfilter:: +.. needlist:: :tags: test;my_test diff --git a/tests/doc_test/doc_style_blank/index.rst b/tests/doc_test/doc_style_blank/index.rst index cd3a0e0bf..eb4c71f6b 100644 --- a/tests/doc_test/doc_style_blank/index.rst +++ b/tests/doc_test/doc_style_blank/index.rst @@ -11,5 +11,5 @@ TEST DOCUMENT .. story:: A story :tags: 1 -.. needfilter:: +.. needlist:: :tags: test;my_test diff --git a/tests/doc_test/doc_style_custom/index.rst b/tests/doc_test/doc_style_custom/index.rst index cd3a0e0bf..eb4c71f6b 100644 --- a/tests/doc_test/doc_style_custom/index.rst +++ b/tests/doc_test/doc_style_custom/index.rst @@ -11,5 +11,5 @@ TEST DOCUMENT .. story:: A story :tags: 1 -.. needfilter:: +.. needlist:: :tags: test;my_test diff --git a/tests/doc_test/doc_style_modern/index.rst b/tests/doc_test/doc_style_modern/index.rst index cd3a0e0bf..eb4c71f6b 100644 --- a/tests/doc_test/doc_style_modern/index.rst +++ b/tests/doc_test/doc_style_modern/index.rst @@ -11,5 +11,5 @@ TEST DOCUMENT .. story:: A story :tags: 1 -.. needfilter:: +.. needlist:: :tags: test;my_test diff --git a/tests/doc_test/doc_style_unknown/index.rst b/tests/doc_test/doc_style_unknown/index.rst index cd3a0e0bf..eb4c71f6b 100644 --- a/tests/doc_test/doc_style_unknown/index.rst +++ b/tests/doc_test/doc_style_unknown/index.rst @@ -11,5 +11,5 @@ TEST DOCUMENT .. story:: A story :tags: 1 -.. needfilter:: +.. needlist:: :tags: test;my_test diff --git a/tests/doc_test/filter_doc/filter_all.rst b/tests/doc_test/filter_doc/filter_all.rst index 1cd55f491..974be8c5d 100644 --- a/tests/doc_test/filter_doc/filter_all.rst +++ b/tests/doc_test/filter_doc/filter_all.rst @@ -38,8 +38,8 @@ filter_all My test content -.. needfilter:: +.. needlist:: :filter: ("1" in tags or "2" in tags) and ("story" == type or "closed" == status) -.. needfilter:: +.. needlist:: :filter: "test" in title and "test" in status and "test" in content and "TEST" in id \ No newline at end of file diff --git a/tests/doc_test/filter_doc/filter_search.rst b/tests/doc_test/filter_doc/filter_search.rst index ce6613f85..9ccd20ed5 100644 --- a/tests/doc_test/filter_doc/filter_search.rst +++ b/tests/doc_test/filter_doc/filter_search.rst @@ -41,8 +41,8 @@ filter_search me@myemail.com -.. needfilter:: +.. needlist:: :filter: search("A", id) and "filter_search" in tags -.. needfilter:: +.. needlist:: :filter: search(r"(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$)", content) and type=="test" \ No newline at end of file diff --git a/tests/doc_test/filter_doc/filter_tags_or.rst b/tests/doc_test/filter_doc/filter_tags_or.rst index 85a21c455..44a139334 100644 --- a/tests/doc_test/filter_doc/filter_tags_or.rst +++ b/tests/doc_test/filter_doc/filter_tags_or.rst @@ -15,5 +15,5 @@ Testing filter with and or :tags: 1;2 :duration: 1 -.. needfilter:: +.. needlist:: :filter: "1" in tags or "2" in tags diff --git a/tests/doc_test/filter_doc/index.rst b/tests/doc_test/filter_doc/index.rst index 982b6ee9e..340225a0a 100644 --- a/tests/doc_test/filter_doc/index.rst +++ b/tests/doc_test/filter_doc/index.rst @@ -22,7 +22,7 @@ Testing simple filter .. story:: story_a_b_1 :tags: a;b -.. needfilter:: +.. needlist:: :filter: "a" in tags @@ -42,16 +42,16 @@ Testing filter with and or :tags: 1;2 :duration: 1 -.. needfilter:: +.. needlist:: :filter: "1" in tags and "2" in tags Testing bad filters ------------------- -.. needfilter:: +.. needlist:: :filter: xxx -.. needfilter:: +.. needlist:: :filter: 1 .. needlist::