docs: Document documenting Meson

docs/markdown/Yaml-RefMan.md

@@ -0,0 +1,190 @@
+---
+title: YAML Reference manual
+short-description: Editing and maintaining the Reference manual
+...
+
+# Reference Manual
+
+The [Reference Manual](RefMan.md) is automatically generated out of YAML
+files in `docs/yaml`. This allows the Meson project to enforce a consistent
+style of the Reference Manual and enables easier style changes to the generated
+Markdown files without touching the actual documentation.
+Additionally, multiple generation backends can be supported (besides the
+Markdown generator for mesonbuild.com).
+
+The generator that reads these YAML files is located in `docs/refman`, with the
+main executable being `docs/genrefman.py`.
+
+## Linking to the Reference Manual
+
+Links to the Reference Manual can be inserted *anywhere* in the Meson docs with
+tags like this: `[[<tag>]]`. This guarantees that links remain stable (even if
+the structure of the Reference Manual changes) and are uniformly formatted
+everywhere.
+
+To link to functions, the function name should be put into the tag:
+`[[<func name>]]`.
+Methods (for all kinds of objects, including modules) can be linked to like
+this: `[[<object name>.<method name>]]`.
+To link to objects themself, the `[[@<object name>]]` syntax can be used.
+
+These tags do **not** need to be put in inline code! A hotdoc extension handles
+the formatting here. If tags need to be placed (for instance, to include reference
+directly in code blocks), the `[[#<remaining tag>]]` syntax should be used.
+
+Examples:
+- Functions: [[executable]]
+- Methods: [[meson.version]]
+- Objects: [[@str]]
+
+Now the same in a code block:
+
+```meson
+[[#@str]] [[executable]]('main', [
+    'file_@0@.cpp'.format([[#meson.version]])
+])
+```
+
+
+## Directory structure
+
+The directory structure under `docs/yaml` is important, since it determines how
+the YAML files are interpreted:
+
+- `builtins`: Documentation for builtin objects, such as `meson`
+- `elementary`: Strings, lists, integers, void, etc.
+- `objects`: All Objects returned by functions and methods but **not** modules
+- `functions`: All root meson functions ([[executable]], [[project]], etc.)
+
+Finally, modules are defined inside the `modules` subdirectory. Here, each
+module has its own directory. The module itself **must** be in a file called
+`module.yaml`. All objects returned by the module are then located next to this
+file.
+
+The name of the YAML files themself are ignored (with the exception of
+`module.yaml`) and carry no specific meaning. However, it is recommended to name
+the YAML files after the `name` entry of the object.
+
+All objects and functions whose name starts with a `_` are marked as private and
+are *not* exported in the final documents. The primary purpose of these files
+is to make inheriting functions and arguments easier.
+
+
+
+# YAML schema
+
+The YAML files themself are structured as follows:
+
+## Functions
+
+```yaml
+name: executable     # The name of the function                [required]
+returns: build_tgt   # Must be a `name` of an existing object  [required]
+description: |
+  The first line until the first dot of the description is the brief.
+  All other lines are not part of the brief and should document the function
+
+  Here the full Markdown syntax is supported, such as links, `inline code`,
+  code blocks, and references to other parts of the Reference Manual: [[@str]].
+
+  This is true for **all** description keys in all YAML files. Defining a
+  description is **always** required.
+
+since:      0.42.0       # A valid Meson version
+deprecated: 100.99.0     # A valid Meson version
+
+example: |
+  Similar to `description`, but is put under a different section and should
+  contain an example.
+
+notes:
+- A list of notes that should stand out.
+- Should be used sparingly.
+- Notes are optional.
+
+warnings:
+- Similar to notes, but a warning
+- Warnings are also optional.
+
+
+# To avoid duplicating documentation / code, argument inheritence is supported with
+# the following optional keys:
+
+posargs_inherit: _build_target_base  # Use the posargs definition of `_build_target_base` here
+optargs_inherit: _build_target_base  # Use the optargs definition of `_build_target_base` here
+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
+
+
+posargs:
+  arg_name:
+    type: bool | dep           # [required]
+    description: Some text.    # [required]
+    since: 0.42.0
+    deprecated: 100.99.0
+    default: false             # Is technically supported buy should **not** be used for posargs
+
+  another_arg:
+    ...
+
+optargs:
+  optional_arg:
+    type: int                  # [required]
+    description: Hello World   # [required]
+    since: 0.42.0
+    deprecated: 100.99.0
+    default: false             # Default values can make sense here
+
+  next_arg:
+    ...
+
+varargs:
+  name: Some name                # [required]
+  type: str | list[str | int]    # [required]
+  description: Some helpful text # [required]
+  since: 0.42.0
+  deprecated: 100.99.0
+  min_varargs: 1
+  max_varargs: 21
+
+
+kwargs:
+  kwarg_name:
+    type: str                      # [required]
+    description: Meson is great!   # [required]
+    since: 0.42.0
+    deprecated: 100.99.0
+    default: false
+    required: false                # Some kwargs may be required
+```
+
+
+## Objects
+
+```yaml
+name: build_tgt                       # [required]
+long_name: Build target               # [required]
+description: Just some description.   # [required]
+example: Same as for functions
+
+# Objects can be marked as containers. In this case they can be used in a `type`
+# like this `container[held | objects]`. Currently this only makes sense for
+# lists and dicts. There is almost no reason to set this to true for other objects.
+is_container: true
+
+since:      0.42.0
+deprecated: 100.99.0
+
+# Notes and warnings work the same as with functions
+notes:
+warnings:
+
+# Inheritance is also supported for objects. Here all methods from the parent
+# object are inherited. The trick with `_private` objects also works here
+# to help with more complex structures.
+extends: tgt
+
+# Methods are a list of functions (see the previous section).
+methods:
+- ...
+```

docs/sitemap.txt

@@ -131,6 +131,7 @@ index.md
 		Using-multiple-build-directories.md
 		Vs-External.md
 	Contributing.md
+		Yaml-RefMan.md
 		MesonCI.md
 	legal.md
 	Videos.md