add documentation for with_file loops

This commit adds documentation for the `with_file` loop construct,
resolving #7890 and #9160.

1 files changed, 29 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_loops.rst b/docsite/rst/playbooks_loops.rst
index fef48ca49a..b25e95941e 100644
--- a/docsite/rst/playbooks_loops.rst
+++ b/docsite/rst/playbooks_loops.rst
@@ -93,6 +93,35 @@ And you want to print every user's name and phone number.  You can loop through
 
 .. _looping_over_fileglobs:
 
+Looping over Files
+``````````````````
+
+``with_file`` iterates over a list of files, setting `item` to the content of each file in sequence.  It can be used like this::
+
+    ---
+    - hosts: all
+
+      tasks:
+
+        # emit a debug message containing the content of each file.
+        - debug:
+            msg: "{{item}}"
+          with_file:
+            - first_example_file
+            - second_example_file
+
+Assuming that ``first_example_file`` contained the text "hello" and ``second_example_file`` contained the text "world", this would result in::
+
+    TASK [debug msg={{item}}] ******************************************************
+    ok: [localhost] => (item=hello) => {
+        "item": "hello", 
+        "msg": "hello"
+    }
+    ok: [localhost] => (item=world) => {
+        "item": "world", 
+        "msg": "world"
+    }
+
 Looping over Fileglobs
 ``````````````````````