docs: refman: Add `arg_flattening` support

8 files changed, 27 insertions, 8 deletions

diff --git a/docs/jsonvalidator.py b/docs/jsonvalidator.py
index 6a55ddb..1b2c637 100755
--- a/docs/jsonvalidator.py
+++ b/docs/jsonvalidator.py
@@ -82,6 +82,7 @@ def validate_function(path: str, name: str, func: dict) -> None:
         'optargs': dict,
         'kwargs': dict,
         'varargs': (dict, T_None),
+        'arg_flattening': bool,
     }
     cur = assert_has_typed_keys(f'{path}.{name}', func, expected)
     assert not func, f'{path}.{name} has extra keys: {func.keys()}'
diff --git a/docs/markdown/Yaml-RefMan.md b/docs/markdown/Yaml-RefMan.md
index ed7770d..b59e4e6 100644
--- a/docs/markdown/Yaml-RefMan.md
+++ b/docs/markdown/Yaml-RefMan.md
@@ -18,6 +18,11 @@ the yaml manual using a strict subset of yaml at the cost of loading slowly.
 You may optionally disable all these safety checks using the `fastyaml` loader,
 which will significantly speed things up at the cost of being less correct.
 
+The following python packages are required for the `genrefman` script:
+
+- chevron
+- strictyaml
+
 ## Linking to the Reference Manual
 
 Links to the Reference Manual can be inserted *anywhere* in the Meson docs with
@@ -118,6 +123,9 @@ optargs_inherit: _build_target_base  # Use the optargs definition of `_build_tar
 varargs_inherit: _build_target_base  # Use the varargs definition of `_build_target_base` here
 kwargs_inherit: _build_target_base   # Add all kwargs of `_build_target_base` to this function
 
+# Whether argument flattening (see Syntax.md) is enabled
+# for this function. Defaults to `true`.
+args_flattening: true
 
 posargs:
   arg_name:
diff --git a/docs/refman/generatorjson.py b/docs/refman/generatorjson.py
index 9f92342..d41cb71 100644
--- a/docs/refman/generatorjson.py
+++ b/docs/refman/generatorjson.py
@@ -72,6 +72,7 @@ class GeneratorJSON(GeneratorBase):
             'optargs': {x.name: self._generate_arg(x, True) for x in func.optargs},
             'kwargs': {x.name: self._generate_arg(x) for x in self.sorted_and_filtered(list(func.kwargs.values()))},
             'varargs': self._generate_arg(func.varargs) if func.varargs else None,
+            'arg_flattening': func.arg_flattening,
         }
 
     def _generate_objects(self, obj: Object) -> J.Object:
diff --git a/docs/refman/generatormd.py b/docs/refman/generatormd.py
index 42a0ee0..8fd0ef9 100644
--- a/docs/refman/generatormd.py
+++ b/docs/refman/generatormd.py
@@ -267,6 +267,7 @@ class GeneratorMD(GeneratorBase):
             } if func.posargs or func.optargs else None,
             'kwargs':  {'args': [gen_arg_data(x) for x in self.sorted_and_filtered(list(func.kwargs.values()))]} if func.kwargs else None,
             'varargs': gen_arg_data(func.varargs) if func.varargs else None,
+            'arg_flattening': func.arg_flattening,
 
             # For the feature taggs template
             'since': func.since or None,
diff --git a/docs/refman/jsonschema.py b/docs/refman/jsonschema.py
index 6d6f98a..1b94856 100644
--- a/docs/refman/jsonschema.py
+++ b/docs/refman/jsonschema.py
@@ -8,7 +8,7 @@ import typing as T
 # the Meson version
 
 VERSION_MAJOR = 1  # Changes here indicate breaking format changes (changes to existing keys)
-VERSION_MINOR = 0  # Changes here indicate non-breaking changes (only new keys are added to the existing structure)
+VERSION_MINOR = 1  # Changes here indicate non-breaking changes (only new keys are added to the existing structure)
 
 class BaseObject(T.TypedDict):
     '''
@@ -43,13 +43,14 @@ class Function(BaseObject):
     '''
         Represents a function or method.
     '''
-    returns:     T.List[Type]  # A non-empty list of types that are supported.
-    returns_str: str           # Formated version of `returns`. Is guranteed to not contain any whitespaces.
-    example:     T.Optional[str]
-    posargs:     T.Dict[str, Argument]
-    optargs:     T.Dict[str, Argument]
-    kwargs:      T.Dict[str, Argument]
-    varargs:     T.Optional[Argument]
+    returns:        T.List[Type]  # A non-empty list of types that are supported.
+    returns_str:    str           # Formatted version of `returns`. Is guaranteed to not contain any whitespaces.
+    example:        T.Optional[str]
+    posargs:        T.Dict[str, Argument]
+    optargs:        T.Dict[str, Argument]
+    kwargs:         T.Dict[str, Argument]
+    varargs:        T.Optional[Argument]
+    arg_flattening: bool
 
 class Object(BaseObject):
     '''
diff --git a/docs/refman/loaderyaml.py b/docs/refman/loaderyaml.py
index 8f56d79..fc06b0d 100644
--- a/docs/refman/loaderyaml.py
+++ b/docs/refman/loaderyaml.py
@@ -89,6 +89,7 @@ class StrictTemplate(Template):
             Optional('varargs_inherit', default=''): Str(),
             Optional('kwargs'): MapPattern(Str(), self.s_kwarg),
             Optional('kwargs_inherit', default=[]): OrValidator(OrValidator(Seq(Str()), EmptyList()), Str()),
+            Optional('arg_flattening', default=True): Bool(),
         })
 
         self.s_object = Map({
@@ -138,6 +139,7 @@ class FastTemplate(Template):
         'varargs_inherit': '',
         'kwargs': {},
         'kwargs_inherit': [],
+        'arg_flattening': True,
     }
 
     s_object = {
diff --git a/docs/refman/model.py b/docs/refman/model.py
index 8a051c9..0c65c58 100644
--- a/docs/refman/model.py
+++ b/docs/refman/model.py
@@ -77,6 +77,7 @@ class Function(NamedObject, FetureCheck):
     optargs_inherit: str
     varargs_inherit: str
     kwargs_inherit: T.List[str]
+    arg_flattening: bool
 
 @dataclass
 class Method(Function):
diff --git a/docs/refman/templates/func.mustache b/docs/refman/templates/func.mustache
index 3e6209f..c601f78 100644
--- a/docs/refman/templates/func.mustache
+++ b/docs/refman/templates/func.mustache
@@ -25,6 +25,10 @@
   <p style="padding: 5px; margin: 0px;"></p> <!-- A bit more space -->
 
   {{base_level}}## Arguments
+
+{{^arg_flattening}}
+  [Argument flattening](Syntax.md#argument-flattening) is **NOT SUPPORTED** by this function.
+{{/arg_flattening}}
 {{/has_args}}
 
 {{#posargs}}