docs: Add docs for structured_sources

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
+```

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:

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

docs/yaml/objects/structured_src.yaml

@@ -0,0 +1,3 @@
+name: structured_src
+long_name: Structured Source
+description: Opaque object returned by [[structured_sources]].