diff options
-rw-r--r-- | docs/markdown/Yaml-RefMan.md | 190 | ||||
-rw-r--r-- | docs/sitemap.txt | 1 |
2 files changed, 191 insertions, 0 deletions
diff --git a/docs/markdown/Yaml-RefMan.md b/docs/markdown/Yaml-RefMan.md new file mode 100644 index 0000000..704bddf --- /dev/null +++ b/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: +- ... +``` diff --git a/docs/sitemap.txt b/docs/sitemap.txt index c0ae7d5..3dbcca4 100644 --- a/docs/sitemap.txt +++ b/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 |