文档 widget

文档 widget 可以简化文档使用的单一来源信息。

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

所有文档微件都在 //docs/_common/_doc_widgets.md 中定义。

必备条件：（仅适用于 HTML/Jinja2）

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


{% 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 之前请务必指定前提条件。

术语库

这些微件专门用来与 //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。
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 必需
为防止出错，必须提供此参数，但不执行任何操作。