リファレンスマニュアル

リファレンスマニュアルは、docs/yaml の YAML ファイルから自動的に生成されます。これにより、Meson プロジェクトはリファレンスマニュアルの一貫したスタイルを適用でき、実際のドキュメントには触れずに、生成されたマークダウンファイルへのスタイル変更を容易にすることができます。さらに、（mesonbuild.com のマークダウンジェネレーターに加えて）複数の生成バックエンドをサポートできます。

これらの YAML ファイルを読み取るジェネレーターは docs/refman にあり、メインの実行可能ファイルは docs/genrefman.py です。デフォルトでは genrefman.py は、読み込みが遅くなるという犠牲を払って、strictyaml のサブセットを使用して yaml マニュアルを読み込みます。fastyaml ローダーを使用して、これらのすべての安全検査を無効にすることもできます。これにより、正確さが低下するという犠牲を払って作業が大幅に高速化されます。

genrefman スクリプトには、次の Python パッケージが必要です。

chevron
strictyaml

リファレンスマニュアルへのリンク

リファレンスマニュアルへのリンクは、次のようなタグを使用して、Meson ドキュメントの どこからでも 挿入できます。[[<tag>]]。これにより、たとえリファレンスマニュアルの構造が変更されても、リンクが安定したままになり、どこでも一様にフォーマットされます。

関数にリンクするには、関数名をタグに入れます: [[<func name>]]。メソッド（モジュールを含むあらゆる種類のオブジェクト）には、次のようにリンクできます: [[<object name>.<method name>]]。オブジェクト自体にリンクするには、[[@<object name>]] 構文を使用できます。

これらのタグはインラインコード内に置く 必要はありません！Hotdoc 拡張機能がここで書式設定を処理します。タグを配置する必要がある場合（例えば、参照をコードブロックに直接含める場合）、[[#<remaining tag>]] 構文を使用する必要があります。

例

関数: executable()
メソッド: meson.version()
オブジェクト: str

コードブロック内の同じ内容

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

ディレクトリ構造

docs/yaml のディレクトリ構造は、YAML ファイルの解釈方法を決定するため重要です。

builtins: meson などの組み込みオブジェクトのドキュメント
elementary: 文字列、リスト、整数、void など
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:
- ...

検索の結果は

GitHub で編集する