api: Add details forparams_show stages syntax.

Explain `stages` syntax for cases where the api is used from a directory different to the one the `dvc.yam` is located.

dvc/api/params.py

@@ -37,6 +37,10 @@ def params_show(
             stages to retrieve parameters from.
             Defaults to `None`.
             If `None`, all parameters from all stages will be retrieved.
+            If this method is called from a different location to the one where
+            the `dvc.yaml` is found, the relative path to the `dvc.yaml` must
+            be provided as a prefix with the syntax `{relpath}:{stage}`.
+            For example: `subdir/dvc.yaml:stage-0` or `../dvc.yaml:stage-1`.
         rev (str, optional): Name of the `Git revision`_ to retrieve parameters
             from.
             Defaults to `None`.

tests/func/api/test_params.py

@@ -1,3 +1,4 @@
+import os
 from textwrap import dedent
 
 import pytest
@@ -95,6 +96,27 @@ def test_params_show_stages(params_repo):
         api.params_show(stages="stage-0")
 
 
+def test_params_show_stage_addressing(tmp_dir, dvc):
+    for subdir in {"subdir1", "subdir2"}:
+        subdir = tmp_dir / subdir
+        subdir.mkdir()
+        with subdir.chdir():
+            subdir.gen("params.yaml", "foo: 1")
+
+            dvc.run(name="stage-0", cmd="echo stage-0", params=["foo"])
+
+    for s in {"subdir1", "subdir2"}:
+        dvcyaml = os.path.join(s, "dvc.yaml")
+        assert api.params_show(stages=f"{dvcyaml}:stage-0") == {"foo": 1}
+
+    with subdir.chdir():
+        nested = subdir / "nested"
+        nested.mkdir()
+        with nested.chdir():
+            dvcyaml = os.path.join("..", "dvc.yaml")
+            assert api.params_show(stages=f"{dvcyaml}:stage-0") == {"foo": 1}
+
+
 def test_params_show_revs(params_repo):
     assert api.params_show(rev="HEAD~1") == {
         "params.yaml:foo": 1,