docs: Specify how the recursive argument to directory() works

- As described in issue #1435, the 'recursive' argument to
  files.directory() does not ensure recursive ownership of the entire
  directory tree.  Only ownership of the top-level directory is
  checked, not that of the subdirectories and files.  Specifying
  'recursive=True' will have no effect if the top-level directory
  already matches the mode, user, and group.
- This is how the operation has behaved for a long time, so changing
  existing functionality to check the entire tree could be
  undesirable.  It also takes more time to check the entire tree, so
  doing so affects performance.  A new option may be provided in the
  future for callers to explicitly check the whole tree when this is
  desired.
- Documented the existing behaviour of 'recursive' in the
  files.directory() docstring.

Author: cliffmccarthy

src/pyinfra/operations/files.py

@@ -1569,6 +1569,12 @@ def directory(
     + force_backup: set to ``False`` to remove any existing non-file when ``force=True``
     + force_backup_dir: directory to move any backup to when ``force=True``
 
+    ``recursive``:
+        Mode is only applied recursively if the base directory mode does not match
+        the specified value.  User and group are both applied recursively if the
+        base directory does not match either one; otherwise they are unchanged for
+        the whole tree.
+
     **Examples:**
 
     .. code:: python