Referenzhandbuch

Das Referenzhandbuch wird automatisch aus YAML-Dateien in docs/yaml generiert. Dies ermöglicht es dem Meson-Projekt, einen konsistenten Stil des Referenzhandbuchs durchzusetzen und erleichtert Stiländerungen an den generierten Markdown-Dateien, ohne die eigentliche Dokumentation zu berühren. Zusätzlich können mehrere Generierungs-Backends unterstützt werden (neben dem Markdown-Generator für mesonbuild.com).

Der Generator, der diese YAML-Dateien liest, befindet sich in docs/refman, wobei die Hauptausführbare Datei docs/genrefman.py ist. Standardmäßig lädt genrefman.py das YAML-Handbuch mit einer strengen Teilmenge von YAML, was zu langsamen Ladezeiten führt. Sie können optional alle diese Sicherheitsprüfungen mithilfe des fastyaml-Loaders deaktivieren, was die Dinge erheblich beschleunigt, aber weniger korrekt ist.

Die folgenden Python-Pakete sind für das genrefman-Skript erforderlich

• chevron
• strictyaml

Verlinkung zum Referenzhandbuch

Links zum Referenzhandbuch können überall in der Meson-Dokumentation mit Tags wie diesem eingefügt werden: [[<tag>]]. Dies garantiert, dass Links stabil bleiben (auch wenn sich die Struktur des Referenzhandbuchs ändert) und überall einheitlich formatiert sind.

Um auf Funktionen zu verlinken, sollte der Funktionsname in den Tag gesetzt werden: [[<func name>]]. Methoden (für alle Arten von Objekten, einschließlich Module) können wie folgt verlinkt werden: [[<object name>.<method name>]]. Um auf Objekte selbst zu verlinken, kann die Syntax [[@<object name>]] verwendet werden.

Diese Tags müssen nicht in Inline-Code gesetzt werden! Eine Hotdoc-Erweiterung übernimmt hier die Formatierung. Wenn Tags platziert werden müssen (zum Beispiel, um Referenzen direkt in Codeblöcken einzufügen), sollte die Syntax [[#<remaining tag>]] verwendet werden.

Beispiele

• Funktionen: executable()
• Methoden: meson.version()
• Objekte: str

Nun dasselbe in einem Codeblock

str executable('main', [
    'file_@0@.cpp'.format(meson.version())
])

Verzeichnisstruktur

Die Verzeichnisstruktur unter docs/yaml ist wichtig, da sie bestimmt, wie die YAML-Dateien interpretiert werden

• builtins: Dokumentation für eingebaute Objekte wie meson
• elementary: Zeichenketten, Listen, Ganzzahlen, void usw.
• objects: Alle von Funktionen und Methoden zurückgegebenen Objekte, aber nicht Module
• functions: Alle Meson-Root-Funktionen (executable(), project() usw.)

Schließlich sind Module im Unterverzeichnis modules definiert. Hier hat jedes Modul sein eigenes Verzeichnis. Das Modul selbst muss in einer Datei namens module.yaml liegen. Alle vom Modul zurückgegebenen Objekte befinden sich dann neben dieser Datei.

Der Name der YAML-Dateien selbst wird ignoriert (mit Ausnahme von module.yaml) und hat keine spezifische Bedeutung. Es wird jedoch empfohlen, die YAML-Dateien nach dem name-Eintrag des Objekts zu benennen.

Alle Objekte und Funktionen, deren Name mit einem _ beginnt, sind als privat markiert und werden in den endgültigen Dokumenten nicht exportiert. Der Hauptzweck dieser Dateien ist die Vereinfachung der Vererbung von Funktionen und Argumenten.

YAML-Schema

Die YAML-Dateien selbst sind wie folgt strukturiert

Funktionen

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 inheritance 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

# Whether argument flattening (see Syntax.md) is enabled
# for this function. Defaults to `true`.
args_flattening: true

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

Objekte

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:
- ...