文档 widget

文档微件是一种简化信息并将其集中到一个来源的方法，以便在文档中使用。

Fuchsia.dev 文档 widget 是使用 Jinja2 宏创建的，也支持 Markdown 格式。在网页发布到 fuchsia.dev 之前，系统会将微件从 Markdown 转换为实际的 Jinja2 宏。如需详细了解 Jinja2 宏，请参阅宏。

所有文档 widget 均在 //docs/_common/_doc_widgets.md 中定义。

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

您必须先将文档 widget 导入到 Markdown (.md) 文件中，然后才能在 HTML/Jinja2 中使用这些 widget。在文件顶部，指定以下内容：


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

常规微件

inline_toc

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

示例

用法

由于限制，您无法将 _toc.yaml 文件指定为 widget 的参数。


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

参数

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

术语库

这些 widget 专为与 //docs/glossary/glossary.yaml 中定义的术语表格搭配使用而创建。

如需启用悬停定义，您必须使用下列语法之一。建议使用 Markdown 版本。使用任何其他语法都会产生没有悬停定义的简单链接。

如需详细了解如何向术语表中添加术语，请参阅添加术语表条目。

glossary_simple

创建术语的 short_description 悬停定义，并附上指向术语表术语的链接。（可选）此字词可以不可点击。

示例

  • 可点击的悬停定义：

    已渲染

    ABI 的定义

  • 不可点击的悬停定义：

    已渲染

    ABI 定义

用法

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

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 文件中指定将显示悬停文本的文字。

使用 [glossary.term] 的 xref 语法时，不需要提供 display_name。在这种情况下，术语表术语将用作 display_name。
term 必需
指定 _glossary.yaml 文件中定义的术语。

HTML/Jinja2

参数
term 必需
指定 _glossary.yaml 文件中定义的术语。
display_name 可选
在 Markdown 文件中指定将显示悬停文本的文字。
notClickable 可选
（如果使用 display_name，则为必需）用于确定术语是否会显示指向完整术语表的链接。如果未指定此属性，术语将变为可点击，并带有指向其术语表条目的链接。

glossary_box

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

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

示例

  • 定义框：

    已渲染

用法

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

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 必需
此参数是防止出错的必需参数，但不会执行任何操作。