說明文件小工具

說明文件小工具可協助您簡化 使用在說明文件中

Fuchsia.dev 說明文件小工具使用 Jinja2 巨集建立， 也支援 Markdown 格式將小工具從 發布至實際 Jinja2 巨集的 Markdown 巨集會在頁面發布前發生 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 () }}

參數

這個小工具不使用參數，因此請務必指定 必要條件。

詞彙解釋

這些小工具專為處理定義的詞彙表字詞而打造 //docs/glossary/glossary.yaml 中。

如要啟用過度懸停定義，您必須使用下列任一語法。 建議使用 Markdown 版本。如果使用任何其他語法，會產生不含 懸停定義

如要進一步瞭解如何將字詞新增至詞彙表，請參閱 新增詞彙表項目。

glossary_simple

使用含有字詞建立字詞 short_description 的懸停定義定義 詞彙解釋(選用) 這個字詞不可點按。

範例

  • 可點擊的滑鼠遊標懸停定義：

    最終顯示

    「 」的定義 ABI ，直接在 Google Cloud 控制台實際操作。

  • 不可點擊的過度懸停定義：

    最終顯示

    「 」的定義 ABI ，直接在 Google Cloud 控制台實際操作。

用量

這個小工具的幾種使用方式如下：

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。

定義方塊也會顯示編輯按鈕，供協作者編輯 詞彙解釋

範例

  • 定義方塊：

    最終顯示

用量

這個小工具的幾種使用方式如下：

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 必要
此為必要參數以免發生錯誤，但 也不會有任何影響。