說明文件小工具

說明文件小工具可用於簡化文件中的單一來源資訊，以便用於說明文件。

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 () }}

參數

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

詞彙解釋

這些小工具是專為 //docs/glossary/glossary.yaml 中定義的詞彙表字詞而建立。

如要啟用過度懸停定義，您必須使用下列其中一種語法。建議使用標示版本。使用其他語法會產生簡單的連結，而不會產生懸停定義。

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

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 檔案中指定要將遊標懸停在文字上的文字。

使用 [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。

定義方塊還會顯示編輯按鈕，方便協作者編輯詞彙表。

範例

  • 定義方塊：

    已轉譯

用量

這個小工具有幾種使用方式：

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 必要
這是必要參數，可防止錯誤發生，但不會採取任何行動。