文档 widget

文档微件是一种简化单一来源信息的方式， 使用说明。

Fuchsia.dev 文档小部件使用 Jinja2 宏创建， 也支持 Markdown 格式微件从 Markdown 到实际 Jinja2 宏，发生在 fuchsia.dev.如需详细了解 Jinja2 宏，请参阅 宏。

所有文档小部件都在 //docs/_common/_doc_widgets.md.

前提条件：（仅适用于 HTML/Jinja2）

您必须先导入 HTML/Jinja2 中的文档小部件， 导入 Markdown (.md) 文件中在文件顶部，指定 以下：


{% import 'fuchsia-src/_common/_doc_widgets.md' as widgets %}

常规微件

inline_toc

根据 _toc.yaml 文件创建带项目符号的目录 (TOC) 列表。

示例

用法

由于存在限制，您无法将 _toc.yaml 文件指定为 。


{% set tocmeta | yamlloads %}
{% include "_toc_file.yaml" %}
{% endset %}
{{ widgets.inline_toc () }}

参数

此 widget 不使用参数，请务必指定 前提条件。

术语库

这些微件是专门为与定义的术语库术语而创建的 （位于 //docs/glossary/glossary.yaml 中）。

要启用悬停定义，您必须使用下列语法之一。通过 建议使用 Markdown 版本。使用任何其他语法将生成简单链接，而不包含 将鼠标悬停在定义上。

有关向术语库添加术语的详细信息，请参阅 添加术语表条目。

glossary_simple

使用short_description 指向术语库的链接。（可选）此字词也可以不可点击。

示例

  • 可点击悬停的定义：

    已渲染

    的定义 ABI ，了解所有最新动态。

  • 不可点击的悬停的定义：

    已渲染

    的定义 ABI ，了解所有最新动态。

用法

您可以通过多种方式使用此微件：

Markdown

  • Xref 链接（首选）：
[display_name][glossary.term]

或者，您也无需指定 display_name，这样一来，实际的字词 用作 display_name：

[glossary.term]

对于这两种格式，您都必须在 Markdown 文件底部定义 Xref。例如：

[glossary.display_name]: /docs/glossary/README.md#term
  • 内嵌链接：
[display_name](/docs/glossary/README.md#term)
  • 内嵌链接（精简版）：
[display_name](/docs/glossary#term)

HTML/Jinja2

{{ widgets.glossary_simple ('term', 'display_name', 'notClickable')}}

参数

Markdown

参数
display_name 必需

在 Markdown 文件中指定 将鼠标悬停在文字上。

使用 xref 语法时不需要 [glossary.term]。在这种情况下 术语用作 display_name。
term 必需
指定一个已定义的术语 在 _glossary.yaml 文件。

HTML/Jinja2

参数
term 必需
指定一个已定义的术语 在 _glossary.yaml 文件。
display_name 可选
在 Markdown 文件中指定 将鼠标悬停在文字上。
notClickable 可选
如果使用 display_name确定，则为必需 是否提供了指向完整词汇表的链接。如果 指定后，该术语将变为可点击，并显示指向其词汇表的链接 条目。

glossary_box

创建术语的 full_description 的定义框。如果字词 没有 full_description，则使用 short_description。

定义框中还会显示一个修改按钮，供贡献者修改 术语库。

示例

  • 定义框：

    已渲染

    <ph type="x-smartling-placeholder">

用法

您可以通过多种方式使用此微件：

Markdown

  • Xref 链接（首选）：
[display_name][glossary.box.term]

然后，您必须在 Markdown 文件底部定义 Xref。例如：

[glossary.box.display_name]: /docs/glossary/README.md#term
  • 内嵌链接：
[display_name](/docs/glossary/README.md?style=box#term)
  • 内嵌链接（精简版）：
[display_name](/docs/glossary?style=box#term)

HTML/Jinja2

{{ widgets.glossary_box ('term', 'display_name') }}

参数

参数
term 必需
指定一个已定义的术语 在 _glossary.yaml 文件。
display_name 必需属性
为防止出现错误，必须提供此参数，但 不会执行任何操作。