diff --git a/docs/configuration.rst b/docs/configuration.rst index 02f5a116d..adab79933 100644 --- a/docs/configuration.rst +++ b/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: diff --git a/docs/directives/needimport.rst b/docs/directives/needimport.rst index 579260ceb..7d0bf40bc 100644 --- a/docs/directives/needimport.rst +++ b/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 diff --git a/sphinx_needs/config.py b/sphinx_needs/config.py index 1dea1ea2e..de838ff32 100644 --- a/sphinx_needs/config.py +++ b/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,)} ) diff --git a/sphinx_needs/directives/needimport.py b/sphinx_needs/directives/needimport.py index d14ac4a06..dcb9c8b08 100644 --- a/sphinx_needs/directives/needimport.py +++ b/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"): diff --git a/sphinx_needs/external_needs.py b/sphinx_needs/external_needs.py index 08b131e9a..db22f2861 100644 --- a/sphinx_needs/external_needs.py +++ b/sphinx_needs/external_needs.py @@ -77,7 +77,7 @@ def load_external_needs( if os.path.isabs(source["json_path"]): json_path = source["json_path"] else: - json_path = os.path.join(app.srcdir, source["json_path"]) + json_path = os.path.join(app.confdir, source["json_path"]) if not os.path.exists(json_path): raise NeedsExternalException( diff --git a/tests/doc_test/import_doc/conf.py b/tests/doc_test/import_doc/conf.py index 1e6501b34..3cfcfa5ea 100644 --- a/tests/doc_test/import_doc/conf.py +++ b/tests/doc_test/import_doc/conf.py @@ -42,6 +42,8 @@ }, ] +needs_import_keys = {"key": "needs_test.json"} + needs_template = """ .. _{{id}}: diff --git a/tests/doc_test/import_doc/index.rst b/tests/doc_test/import_doc/index.rst index 216c4f5a5..6c2e2f108 100644 --- a/tests/doc_test/import_doc/index.rst +++ b/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