✨ Add needs_import_keys configuration

docs/configuration.rst

@@ -1664,7 +1664,14 @@ Default: ``False``.
     needs_service_all_data = True
 
 
+.. _needs_import_keys:
 
+needs_import_keys
+~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 4.2.0
+
+For use with the :ref:`needimport` directive, mapping keys to file paths, see :ref:`needimport-keys`.
 
 .. _needs_external_needs:
 

docs/directives/needimport.rst

@@ -107,3 +107,23 @@ So you can decide what kind of layout or style to use during import.
 * template
 * pre_template
 * post_template
+
+.. _needimport-keys:
+
+Global keys
+-----------
+.. versionadded:: 4.2.0
+
+The :ref:`needs_import_keys` configuration can be used to set global keys for use as the directive arguments.
+
+For example:
+
+.. code-block:: python
+
+    needs_import_keys = {"my_key": "path/to/needs.json"}
+
+Allows for the use of:
+
+.. code-block:: restructuredtext
+
+    .. needimport:: my_key

sphinx_needs/config.py

@@ -594,6 +594,10 @@ def warnings(
         default=False, metadata={"rebuild": "html", "types": (bool,)}
     )
     """If True, unknown sevice option data is shown in the need content."""
+    import_keys: dict[str, str] = field(
+        default_factory=dict, metadata={"rebuild": "html", "types": (dict,)}
+    )
+    """Mapping of keys that can be used as needimport arguments and replaced by the value."""
     external_needs: list[ExternalSource] = field(
         default_factory=list, metadata={"rebuild": "html", "types": (list,)}
     )

sphinx_needs/directives/needimport.py

@@ -52,14 +52,17 @@ class NeedimportDirective(SphinxDirective):
 
     @measure_time("needimport")
     def run(self) -> Sequence[nodes.Node]:
-        # needs_list = {}
+        needs_config = NeedsSphinxConfig(self.config)
+
         version = self.options.get("version")
         filter_string = self.options.get("filter")
         id_prefix = self.options.get("id_prefix", "")
 
-        need_import_path = self.arguments[0]
+        need_import_path = needs_config.import_keys.get(
+            self.arguments[0], self.arguments[0]
+        )
 
-        # check if given arguemnt is downloadable needs.json path
+        # check if given argument is downloadable needs.json path
         url = urlparse(need_import_path)
         if url.scheme and url.netloc:
             # download needs.json
@@ -141,7 +144,6 @@ def run(self) -> Sequence[nodes.Node]:
                 f"Version {version} not found in needs import file {correct_need_import_path}"
             )
 
-        needs_config = NeedsSphinxConfig(self.config)
         data = needs_import_list["versions"][version]
 
         if ids := self.options.get("ids"):

tests/doc_test/import_doc/conf.py

@@ -42,6 +42,8 @@
     },
 ]
 
+needs_import_keys = {"key": "needs_test.json"}
+
 needs_template = """
 .. _{{id}}:
 

tests/doc_test/import_doc/index.rst

@@ -20,7 +20,7 @@ COLLAPSED
 
 TEST
 ----
-.. needimport:: needs_test.json
+.. needimport:: key
    :id_prefix: test_
    :tags: imported; new_tag