docs: Add docs for structured_sources

4 files changed, 51 insertions, 1 deletions

diff --git a/docs/markdown/snippets/structured_sources.md b/docs/markdown/snippets/structured_sources.md
new file mode 100644
index 0000000..19fdc86
--- /dev/null
+++ b/docs/markdown/snippets/structured_sources.md
@@ -0,0 +1,26 @@
+## structured_sources()
+
+A new function, `structured_sources()` has been added. This function allows
+languages like Rust which depend on the filesystem layout at compile time to mix
+generated and static sources.
+
+```meson
+executable(
+  'main',
+  structured_sources(
+    'main.rs,
+    {'mod' : generated_mod_rs},
+  )
+)
+```
+
+Meson will then at build time copy the files into the build directory (if
+necessary), so that the desired file structure is laid out, and compile that. In
+this case:
+
+```
+root/
+  main.rs
+  mod/
+    mod.rs
+```
diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml
index 68df5d8..4db37f4 100644
--- a/docs/yaml/functions/_build_target_base.yaml
+++ b/docs/yaml/functions/_build_target_base.yaml
@@ -49,7 +49,7 @@ kwargs:
       eg: `cpp_args` for C++
 
   sources:
-    type: str | file | custom_tgt | custom_idx | generated_list
+    type: str | file | custom_tgt | custom_idx | generated_list | structured_src
     description: Additional source files. Same as the source varargs.
 
   build_by_default:
diff --git a/docs/yaml/functions/structured_sources.yaml b/docs/yaml/functions/structured_sources.yaml
new file mode 100644
index 0000000..a5f0a83
--- /dev/null
+++ b/docs/yaml/functions/structured_sources.yaml
@@ -0,0 +1,21 @@
+name: structured_sources
+returns: structured_src
+since: 0.62.0
+description: |
+  Create a StructuredSource object, which is opaque and may be passed as a source
+  to any build_target (including static_library, shared_library, executable,
+  etc.). This is useful for languages like Rust, which use the filesystem layout
+  to determine import names. This is only allowed in Rust targets, and cannot be
+  mixed with non structured inputs.
+
+posargs:
+  root:
+    type: list[str | file | custom_tgt | custom_idx | generated_list]
+    description: Sources to put at the root of the generated structure
+
+optargs:
+  additional:
+    type: dict[str | file | custom_tgt | custom_idx | generated_list]
+    description: |
+      Additional sources, where the key is the directory under the root to place
+      the values
diff --git a/docs/yaml/objects/structured_src.yaml b/docs/yaml/objects/structured_src.yaml
new file mode 100644
index 0000000..839575d
--- /dev/null
+++ b/docs/yaml/objects/structured_src.yaml
@@ -0,0 +1,3 @@
+name: structured_src
+long_name: Structured Source
+description: Opaque object returned by [[structured_sources]].