🔧 Add strict typing for sphinx_needs.roles.need_incoming

pyproject.toml

@@ -114,8 +114,6 @@ module = [
   'sphinx_needs.functions.functions',
   'sphinx_needs.layout',
   'sphinx_needs.needsfile',
-  'sphinx_needs.roles.need_incoming',
-  'sphinx_needs.roles.need_outgoing',
   'sphinx_needs.roles.need_part',
   'sphinx_needs.roles.need_ref',
   'sphinx_needs.services.github',

sphinx_needs/config.py

@@ -171,7 +171,7 @@ def __setattr__(self, name: str, value: Any) -> None:
     extra_links: list[dict[str, Any]] = field(default_factory=list, metadata={"rebuild": "html", "types": ()})
     """List of additional links, which can be used by setting related option
     Values needed for each new link:
-    * name (will also be the option name)
+    * option (will also be the option name)
     * incoming
     * copy_link (copy to common links data. Default: True)
     * color (used for needflow. Default: #000000)

sphinx_needs/data.py

@@ -71,10 +71,10 @@ class NeedsPartType(TypedDict):
     """Content of the part."""
     document: str
     """docname where the part is defined."""
-    links_back: list[str]
-    """List of need IDs, which are referencing this part."""
     links: list[str]
     """List of need IDs, which are referenced by this part."""
+    links_back: list[str]
+    """List of need IDs, which are referencing this part."""
 
 
 class NeedsInfoType(NeedsBaseDataType):
@@ -149,11 +149,14 @@ class NeedsInfoType(NeedsBaseDataType):
     # link information
     links: list[str]
     """List of need IDs, which are referenced by this need."""
+    links_back: list[str]
+    """List of need IDs, which are referencing this need."""
     # TODO there is a lot more dynamically added link information;
     # for each item in needs_extra_links config,
     # you end up with a key named by the "option" field,
     # and then another key named by the "option" field + "_back"
     # these all have value type `list[str]`
+    # back links are all set in process_need_nodes (-> create_back_links) transform
 
     # constraints information
     # set in process_need_nodes (-> process_constraints) transform

sphinx_needs/layout.py

@@ -597,7 +597,7 @@ def meta_all(
         show_empty: bool = False,
     ):
         """
-        ``meta_all()`` excludes by default the output of: ``docname``, ``lineno``, ``target_node``, ``refid``,
+        ``meta_all()`` excludes by default the output of: ``docname``, ``lineno``, ``refid``,
         ``content``, ``collapse``, ``parts``, ``id_parent``,
         ``id_complete``, ``title``, ``full_title``, ``is_part``, ``is_need``,
         ``type_prefix``, ``type_color``, ``type_style``, ``type``, ``type_name``, ``id``,

sphinx_needs/roles/need_incoming.py

@@ -7,10 +7,10 @@
 from sphinx_needs.config import NeedsSphinxConfig
 from sphinx_needs.data import SphinxNeedsData
 from sphinx_needs.errors import NoUri
-from sphinx_needs.utils import check_and_calc_base_url_rel_path, unwrap
+from sphinx_needs.utils import check_and_calc_base_url_rel_path, logger, unwrap
 
 
-class NeedIncoming(nodes.Inline, nodes.Element):
+class NeedIncoming(nodes.Inline, nodes.Element):  # type: ignore
     pass
 
 
@@ -29,7 +29,7 @@ def process_need_incoming(
 
         # Let's check if NeedIncoming shall follow a specific link type
         if "link_type" in node_need_backref.attributes:
-            links_back = ref_need[node_need_backref.attributes["link_type"]]
+            links_back = ref_need[node_need_backref.attributes["link_type"]]  # type: ignore[literal-required]
         # if not, follow back to default links
         else:
             links_back = ref_need["links_back"]
@@ -64,6 +64,7 @@ def process_need_incoming(
                             node_need_backref["reftarget"],
                         )
                     else:
+                        assert target_need["external_url"] is not None, "External URL must not be set"
                         new_node_ref = nodes.reference(target_need["id"], target_need["id"])
                         new_node_ref["refuri"] = check_and_calc_base_url_rel_path(
                             target_need["external_url"], fromdocname
@@ -81,7 +82,7 @@ def process_need_incoming(
                     pass
 
             else:
-                env.warn_node("need %s not found [needs]" % node_need_backref["reftarget"], node_need_backref)
+                logger.warning(f"need {node_need_backref['reftarget']} not found [needs]", location=node_need_backref)
 
         if len(node_link_container.children) == 0:
             node_link_container += nodes.Text("None")

sphinx_needs/roles/need_outgoing.py

@@ -32,7 +32,7 @@ def process_need_outgoing(
 
         # Let's check if NeedIncoming shall follow a specific link type
         if "link_type" in node_need_ref.attributes:
-            links = ref_need[node_need_ref.attributes["link_type"]]
+            links = ref_need[node_need_ref.attributes["link_type"]]  # type: ignore[literal-required]
             link_type = node_need_ref.attributes["link_type"]
         # if not, follow back to default links
         else:
@@ -86,6 +86,7 @@ def process_need_outgoing(
                             node_need_ref["reftarget"],
                         )
                     else:
+                        assert target_need["external_url"] is not None, "External URL must be set"
                         new_node_ref = nodes.reference(target_need["id"], target_need["id"])
                         new_node_ref["refuri"] = check_and_calc_base_url_rel_path(
                             target_need["external_url"], fromdocname