| 1 |
--- |
| 2 |
title: YAML Reference manual |
| 3 |
short-description: Editing and maintaining the Reference manual |
| 4 |
... |
| 5 |
|
| 6 |
# Reference Manual |
| 7 |
|
| 8 |
The [Reference Manual](Reference-manual.md) is automatically generated out of YAML |
| 9 |
files in `docs/yaml`. This allows the Meson project to enforce a consistent |
| 10 |
style of the Reference Manual and enables easier style changes to the generated |
| 11 |
Markdown files without touching the actual documentation. |
| 12 |
Additionally, multiple generation backends can be supported (besides the |
| 13 |
Markdown generator for mesonbuild.com). |
| 14 |
|
| 15 |
The generator that reads these YAML files is located in `docs/refman`, with the |
| 16 |
main executable being `docs/genrefman.py`. By default `genrefman.py` will load |
| 17 |
the yaml manual using a strict subset of yaml at the cost of loading slowly. |
| 18 |
You may optionally disable all these safety checks using the `fastyaml` loader, |
| 19 |
which will significantly speed things up at the cost of being less correct. |
| 20 |
|
| 21 |
The following python packages are required for the `genrefman` script: |
| 22 |
|
| 23 |
- chevron |
| 24 |
- strictyaml |
| 25 |
|
| 26 |
## Linking to the Reference Manual |
| 27 |
|
| 28 |
Links to the Reference Manual can be inserted *anywhere* in the Meson docs with |
| 29 |
tags like this: `[[<tag>]]`. This guarantees that links remain stable (even if |
| 30 |
the structure of the Reference Manual changes) and are uniformly formatted |
| 31 |
everywhere. |
| 32 |
|
| 33 |
To link to functions, the function name should be put into the tag: |
| 34 |
`[[<func name>]]`. |
| 35 |
Methods (for all kinds of objects, including modules) can be linked to like |
| 36 |
this: `[[<object name>.<method name>]]`. |
| 37 |
To link to objects themselves, the `[[@<object name>]]` syntax can be used. |
| 38 |
|
| 39 |
These tags do **not** need to be put in inline code! A hotdoc extension handles |
| 40 |
the formatting here. If tags need to be placed (for instance, to include reference |
| 41 |
directly in code blocks), the `[[#<remaining tag>]]` syntax should be used. |
| 42 |
|
| 43 |
Examples: |
| 44 |
- Functions: [[executable]] |
| 45 |
- Methods: [[meson.version]] |
| 46 |
- Objects: [[@str]] |
| 47 |
|
| 48 |
Now the same in a code block: |
| 49 |
|
| 50 |
```meson |
| 51 |
[[#@str]] [[#executable]]('main', [ |
| 52 |
'file_@[email protected]'.format([[#meson.version]]) |
| 53 |
]) |
| 54 |
``` |
| 55 |
|
| 56 |
|
| 57 |
## Directory structure |
| 58 |
|
| 59 |
The directory structure under `docs/yaml` is important, since it determines how |
| 60 |
the YAML files are interpreted: |
| 61 |
|
| 62 |
- `builtins`: Documentation for builtin objects, such as `meson` |
| 63 |
- `elementary`: Strings, lists, integers, void, etc. |
| 64 |
- `objects`: All Objects returned by functions and methods but **not** modules |
| 65 |
- `functions`: All root meson functions ([[executable]], [[project]], etc.) |
| 66 |
|
| 67 |
Finally, modules are defined inside the `modules` subdirectory. Here, each |
| 68 |
module has its own directory. The module itself **must** be in a file called |
| 69 |
`module.yaml`. All objects returned by the module are then located next to this |
| 70 |
file. |
| 71 |
|
| 72 |
The name of the YAML files themselves are ignored (with the exception of |
| 73 |
`module.yaml`) and carry no specific meaning. However, it is recommended to name |
| 74 |
the YAML files after the `name` entry of the object. |
| 75 |
|
| 76 |
All objects and functions whose name starts with a `_` are marked as private and |
| 77 |
are *not* exported in the final documents. The primary purpose of these files |
| 78 |
is to make inheriting functions and arguments easier. |
| 79 |
|
| 80 |
|
| 81 |
|
| 82 |
# YAML schema |
| 83 |
|
| 84 |
The YAML files themselves are structured as follows: |
| 85 |
|
| 86 |
## Functions |
| 87 |
|
| 88 |
```yaml |
| 89 |
name: executable # The name of the function [required] |
| 90 |
returns: build_tgt # Must be a `name` of an existing object [required] |
| 91 |
description: | |
| 92 |
The first line until the first dot of the description is the brief. |
| 93 |
All other lines are not part of the brief and should document the function |
| 94 |
|
| 95 |
Here the full Markdown syntax is supported, such as links, `inline code`, |
| 96 |
code blocks, and references to other parts of the Reference Manual: [[@str]]. |
| 97 |
|
| 98 |
This is true for **all** description keys in all YAML files. Defining a |
| 99 |
description is **always** required. |
| 100 |
|
| 101 |
since: 0.42.0 # A valid Meson version |
| 102 |
deprecated: 100.99.0 # A valid Meson version |
| 103 |
|
| 104 |
example: | |
| 105 |
Similar to `description`, but is put under a different section and should |
| 106 |
contain an example. |
| 107 |
|
| 108 |
notes: |
| 109 |
- A list of notes that should stand out. |
| 110 |
- Should be used sparingly. |
| 111 |
- Notes are optional. |
| 112 |
|
| 113 |
warnings: |
| 114 |
- Similar to notes, but a warning |
| 115 |
- Warnings are also optional. |
| 116 |
|
| 117 |
|
| 118 |
# To avoid duplicating documentation / code, argument inheritance is supported with |
| 119 |
# the following optional keys: |
| 120 |
|
| 121 |
posargs_inherit: _build_target_base # Use the posargs definition of `_build_target_base` here |
| 122 |
optargs_inherit: _build_target_base # Use the optargs definition of `_build_target_base` here |
| 123 |
varargs_inherit: _build_target_base # Use the varargs definition of `_build_target_base` here |
| 124 |
kwargs_inherit: _build_target_base # Add all kwargs of `_build_target_base` to this function |
| 125 |
|
| 126 |
# Whether argument flattening (see Syntax.md) is enabled |
| 127 |
# for this function. Defaults to `true`. |
| 128 |
args_flattening: true |
| 129 |
|
| 130 |
posargs: |
| 131 |
arg_name: |
| 132 |
type: bool | dep # [required] |
| 133 |
description: Some text. # [required] |
| 134 |
since: 0.42.0 |
| 135 |
deprecated: 100.99.0 |
| 136 |
default: false # Is technically supported buy should **not** be used for posargs |
| 137 |
|
| 138 |
another_arg: |
| 139 |
... |
| 140 |
|
| 141 |
optargs: |
| 142 |
optional_arg: |
| 143 |
type: int # [required] |
| 144 |
description: Hello World # [required] |
| 145 |
since: 0.42.0 |
| 146 |
deprecated: 100.99.0 |
| 147 |
default: false # Default values can make sense here |
| 148 |
|
| 149 |
next_arg: |
| 150 |
... |
| 151 |
|
| 152 |
varargs: |
| 153 |
name: Some name # [required] |
| 154 |
type: str | list[str | int] # [required] |
| 155 |
description: Some helpful text # [required] |
| 156 |
since: 0.42.0 |
| 157 |
deprecated: 100.99.0 |
| 158 |
min_varargs: 1 |
| 159 |
max_varargs: 21 |
| 160 |
|
| 161 |
|
| 162 |
kwargs: |
| 163 |
kwarg_name: |
| 164 |
type: str # [required] |
| 165 |
description: Meson is great! # [required] |
| 166 |
since: 0.42.0 |
| 167 |
deprecated: 100.99.0 |
| 168 |
default: false |
| 169 |
required: false # Some kwargs may be required |
| 170 |
``` |
| 171 |
|
| 172 |
|
| 173 |
## Objects |
| 174 |
|
| 175 |
```yaml |
| 176 |
name: build_tgt # [required] |
| 177 |
long_name: Build target # [required] |
| 178 |
description: Just some description. # [required] |
| 179 |
example: Same as for functions |
| 180 |
|
| 181 |
# Objects can be marked as containers. In this case they can be used in a `type` |
| 182 |
# like this `container[held | objects]`. Currently this only makes sense for |
| 183 |
# lists and dicts. There is almost no reason to set this to true for other objects. |
| 184 |
is_container: true |
| 185 |
|
| 186 |
since: 0.42.0 |
| 187 |
deprecated: 100.99.0 |
| 188 |
|
| 189 |
# Notes and warnings work the same as with functions |
| 190 |
notes: |
| 191 |
warnings: |
| 192 |
|
| 193 |
# Inheritance is also supported for objects. Here all methods from the parent |
| 194 |
# object are inherited. The trick with `_private` objects also works here |
| 195 |
# to help with more complex structures. |
| 196 |
extends: tgt |
| 197 |
|
| 198 |
# Methods are a list of functions (see the previous section). |
| 199 |
methods: |
| 200 |
- ... |
| 201 |
``` |