参考手册

该 参考手册 是从 docs/yaml 中的 YAML 文件自动生成的。这使得 Meson 项目可以强制执行一致的参考手册样式，并使生成的 Markdown 文件更容易进行样式更改，而无需接触实际文档。此外，可以支持多种生成后端（除了 mesonbuild.com 的 Markdown 生成器之外）。

读取这些 YAML 文件的生成器位于 docs/refman 中，主可执行文件为 docs/genrefman.py。默认情况下，genrefman.py 将使用 YAML 的严格子集加载 yaml 手册，代价是加载速度慢。您可以选择使用 fastyaml 加载器禁用所有这些安全检查，这将大大加快速度，但代价是准确性降低。

genrefman 脚本需要以下 Python 包

  • chevron
  • strictyaml

链接到参考手册

可以使用以下类型的标签将链接插入 Meson 文档中的 任何位置：[[<tag>]]。这保证链接保持稳定（即使参考手册的结构发生更改），并且在所有地方都以一致的格式进行格式化。

要链接到函数，应将函数名放入标签中：[[<func name>]]。可以像这样链接到方法（针对所有类型的对象，包括模块）：[[<object name>.<method name>]]。要链接到对象本身，可以使用 [[@<object name>]] 语法。

这些标签 不需要 放在内联代码中！hotdoc 扩展在这里处理格式化。如果需要放置标签（例如，要直接在代码块中包含引用），则应使用 [[#<remaining tag>]] 语法。

示例

现在，在代码块中也是如此

str executable('main', [
    'file_@[email protected]'.format(meson.version())
])

目录结构

docs/yaml 下的目录结构很重要，因为它决定了如何解释 YAML 文件

  • builtins：内置对象的文档，例如 meson
  • elementary：字符串、列表、整数、空值等。
  • objects：由函数和方法返回的所有对象，但 不 包括模块
  • functions：所有根 Meson 函数（executable()、project() 等）

最后，模块定义在 modules 子目录中。在这里，每个模块都有自己的目录。模块本身 必须 位于名为 module.yaml 的文件中。然后，模块返回的所有对象都位于该文件旁边。

YAML 文件本身的名称会被忽略（module.yaml 除外），并且没有任何特定含义。但是，建议将 YAML 文件命名为对象的 name 条目。

所有以 _ 开头的对象和函数都被标记为私有，并且 不 在最终文档中导出。这些文件的主要目的是使继承函数和参数更容易。

YAML 架构

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

对象

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

搜索结果是