clarifying docs with first_found (#36951)

better examlpes as this was never really a task loop, but contained inside the lookup itself
(cherry picked from commit 42d15671d092bb6ac422f8ae2e2905c8d8a77c94)

1 files changed, 44 insertions, 26 deletions

diff --git a/lib/ansible/plugins/lookup/first_found.py b/lib/ansible/plugins/lookup/first_found.py
index 0b066b2507..2798a0d286 100644
--- a/lib/ansible/plugins/lookup/first_found.py
+++ b/lib/ansible/plugins/lookup/first_found.py
@@ -11,6 +11,10 @@ DOCUMENTATION = """
     short_description: return first file found from list
     description:
       - this lookup checks a list of files and paths and returns the full path to the first combination found.
+      - As all lookups, when fed relative paths it will try use the current task's location first and go up the chain
+        to the containing role/play/include/etc's location.
+      - The list of files has precedence over the paths searched.
+        i.e, A task in a  role has a 'file1' in the play's relative path, this will be used, 'file2' in role's relative path will not.
     options:
       _terms:
         description: list of file names
@@ -20,38 +24,52 @@ DOCUMENTATION = """
 """
 
 EXAMPLES = """
-- name: show first existin file
-  debug: var=item
-  with_first_found:
-    - "/path/to/foo.txt"
-    - "bar.txt"  # will be looked in files/ dir relative to play or in role
-    - "/path/to/biz.txt"
-
-- name: copy first existing file found to /some/file
-  copy: src={{item}} dest=/some/file
-  with_first_found:
-    - foo
-    - "{{inventory_hostname}}
-    - bar
+- name: show first existing file
+  debug: msg={{lookup('first_found', findme)}}
+  vars:
+    findme:
+      - "/path/to/foo.txt"
+      - "bar.txt"  # will be looked in files/ dir relative to role and/or play
+      - "/path/to/biz.txt"
+
+- name: |
+        copy first existing file found to /some/file,
+        looking in relative directories from where the task is defined and
+        including any play objects that contain it
+  copy: src={{lookup('first_found', findme)}} dest=/some/file
+  vars:
+    findme:
+      - foo
+      - "{{inventory_hostname}}
+      - bar
 
 - name: same copy but specific paths
-  copy: src={{item}} dest=/some/file
-  with_first_found:
-    - files:
-        - foo
-        - "{{inventory_hostname}}
-        - bar
-      paths:
-        - /tmp/production
-        - /tmp/staging
+  copy: src={{lookup('first_found', findme, mypaths}} dest=/some/file
+  vars:
+    findme:
+      - foo
+      - "{{inventory_hostname}}
+      - bar
+    mypaths:
+      - /tmp/production
+      - /tmp/staging
 
 - name: INTERFACES | Create Ansible header for /etc/network/interfaces
   template:
-    src: "{{ item }}"
+    src: "{{ lookup('first_found', findme)}}"
     dest: "/etc/foo.conf"
-  with_first_found:
-    - "{{ ansible_virtualization_type }}_foo.conf"
-    - "default_foo.conf"
+  vars:
+    findme:
+      - "{{ ansible_virtualization_type }}_foo.conf"
+      - "default_foo.conf"
+
+- name: read vars from first file found, use 'vars/' relative subdir
+  include_vars: "{{lookup('first_found', findme, paths=['vars'])}}"
+  vars:
+    findme:
+     - '{{ansible_os_distribution}}.yml'
+     - '{{ansible_os_family}}.yml'
+     - default.yml
 """
 
 RETURN = """