filetree: Add documentation for lookup plugin (#26157)

* filetree: Add documentation for lookup plugin

This is the missing documentation for the filetree lookup plugin.

* Fix typo

* Edits for grammar and clarity

docs/docsite/rst/playbooks_loops.rst

@@ -176,18 +176,81 @@ Looping over Fileglobs
 
 .. note:: When using a relative path with ``with_fileglob`` in a role, Ansible resolves the path relative to the `roles/<rolename>/files` directory.
 
+
+Looping over Filetrees
+``````````````````````
+
+``with_filetree`` recursively matches all files in a directory tree, enabling you to template a complete tree of files on a target system while retaining permissions and ownership.
+
+The ``filetree`` lookup-plugin supports directories, files and symlinks, including SELinux and other file properties. Here is a complete list of what each file object consists of:
+
+* src
+* root
+* path
+* mode
+* state
+* owner
+* group
+* seuser
+* serole
+* setype
+* selevel
+* uid
+* gid
+* size
+* mtime
+* ctime
+
+If you provide more than one path, it will implement a ``with_first_found`` logic, and will not process entries it already processed in previous paths. This enables the user to merge different trees in order of importance, or add role_vars specific paths to influence different instances of the same role.
+
+Here is an example of how we use with_filetree within a role. The ``web/`` path is relative to either ``roles/<role>/files/`` or ``files/``::
+
+    ---
+    - name: Create directories
+      file:
+        path: /web/{{ item.path }}
+        state: directory
+        mode: '{{ item.mode }}'
+      with_filetree: web/
+      when: item.state == 'directory'
+
+    - name: Template files
+      template:
+        src: '{{ item.src }}'
+        dest: /web/{{ item.path }}
+        mode: '{{ item.mode }}'
+      with_filetree: web/
+      when: item.state == 'file'
+
+    - name: Recreate symlinks
+      file:
+        src: '{{ item.src }}'
+        dest: /web/{{ item.path }}
+        state: link
+        force: yes
+        mode: '{{ item.mode }}'
+      with_filetree: web/
+      when: item.state == 'link'
+
+
+The following properties are also available:
+
+* ``root``: allows filtering by original location
+* ``path``: contains the relative path to root
+* ``uidi``, ``gid``: force-create by exact id, rather than by name
+* ``size``, ``mtime``, ``ctime``: filter out files by size, mtime or ctime
+
+
 Looping over Parallel Sets of Data
 ``````````````````````````````````
 
-.. note:: This is an uncommon thing to want to do, but we're documenting it for completeness.  You probably won't be reaching for this one often.
-
-Suppose you have the following variable data was loaded in via somewhere::
+Suppose you have the following variable data::
 
     ---
     alpha: [ 'a', 'b', 'c', 'd' ]
     numbers:  [ 1, 2, 3, 4 ]
 
-And you want the set of '(a, 1)' and '(b, 2)' and so on.   Use 'with_together' to get this::
+...and you want the set of '(a, 1)' and '(b, 2)'.   Use 'with_together' to get this::
 
     tasks:
         - debug:
@@ -202,7 +265,7 @@ Looping over Subelements
 Suppose you want to do something like loop over a list of users, creating them, and allowing them to login by a certain set of
 SSH keys.
 
-How might that be accomplished?  Let's assume you had the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file::
+In this example, we'll assume you have the following defined and loaded in via "vars_files" or maybe a "group_vars/all" file::
 
     ---
     users:
@@ -231,7 +294,7 @@ How might that be accomplished?  Let's assume you had the following defined and
               - "*.*:SELECT"
               - "DB2.*:ALL"
 
-It might happen like so::
+You could loop over these subelements like this::
 
     - name: Create User
       user: