文档 widget

文档微件可简化文档中使用的信息并提供单一信息来源。

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

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

前提条件：（仅限 HTML/Jinja2）

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


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

常规 widget

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

用法

您可以通过多种方式使用此 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] 的交叉引用语法，则不需要此参数。在这种情况下，词汇表术语会用作 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 必需
此参数是必需的，可防止出现错误，但不会执行任何操作。