Debian Codegraph @

subprojects/meson-docs/docs/markdown/Yaml-RefMan.md

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