docs: Add the YAML Reference manual

1 files changed, 94 insertions, 0 deletions

diff --git a/docs/yaml/functions/install_subdir.yaml b/docs/yaml/functions/install_subdir.yaml
new file mode 100644
index 000000000..a57bd27d5
--- /dev/null
+++ b/docs/yaml/functions/install_subdir.yaml
@@ -0,0 +1,94 @@
+name: install_subdir
+returns: void
+description: |
+  Installs the entire given subdirectory and its contents from the
+  source tree to the location specified by the keyword argument
+  `install_dir`.
+
+  If the subdirectory does not exist in the source tree, an empty directory is
+  created in the specified location. *(since 0.45.0)* A newly created
+  subdirectory may only be created in the keyword argument `install_dir`.
+
+example: |
+  For a given directory `foo`:
+  ```text
+  foo/
+    bar/
+      file1
+    file2
+  ```
+  `install_subdir('foo', install_dir : 'share', strip_directory : false)` creates
+  ```text
+  share/
+    foo/
+      bar/
+        file1
+      file2
+  ```
+
+  `install_subdir('foo', install_dir : 'share', strip_directory : true)` creates
+  ```text
+  share/
+    bar/
+      file1
+    file2
+  ```
+
+  `install_subdir('foo/bar', install_dir : 'share', strip_directory : false)` creates
+  ```text
+  share/
+    bar/
+      file1
+  ```
+
+  `install_subdir('foo/bar', install_dir : 'share', strip_directory : true)` creates
+  ```text
+  share/
+    file1
+  ```
+
+  `install_subdir('new_directory', install_dir : 'share')` creates
+  ```text
+  share/
+    new_directory/
+  ```
+
+posargs:
+  subdir_name:
+    type: str
+    description: The sub-directory to install
+
+kwargs:
+  install_mode:
+    type: list[str | int]
+    since: 0.47.0
+    description: |
+      Specify the file mode in symbolic format
+      and optionally the owner/uid and group/gid for the installed files.
+
+      See the `install_mode` kwarg of [[install_data]] for more information.
+
+  exclude_files:
+    type: list[str]
+    description: |
+      A list of file names that should not be installed.
+      Names are interpreted as paths relative to the `subdir_name` location.
+
+  exclude_directories:
+    type: list[str]
+    since: 0.47.0
+    description: |
+      A list of directory names that should not be installed.
+      Names are interpreted as paths relative to the `subdir_name` location.
+
+  install_dir:
+    type: str
+    description: Where to install to.
+
+  strip_directory:
+    type: bool
+    since: 0.45.0
+    default: false
+    description: |
+      Install directory contents.
+      If `strip_directory=true` only the last component of the source path is used.