說明文件小工具

說明文件小工具可用來簡化資訊，並提供單一來源資訊，供說明文件使用。

Fuchsia.dev 說明文件小工具是使用 Jinja2 巨集建立，也支援 Markdown 格式。在網頁發布至 fuchsia.dev 之前，系統會將小工具從 Markdown 轉換為實際的 Jinja2 巨集。如要進一步瞭解 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 檔案指定為小工具的參數。


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

參數

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

詞彙解釋

這些小工具是專門用於搭配 //docs/glossary/glossary.yaml 中定義的詞彙表字詞。

如要啟用懸停定義，您必須使用下列其中一種語法。建議使用 Markdown 版本。使用任何其他語法會產生簡單連結，但不會顯示滑鼠懸停定義。

如要進一步瞭解如何在字典中新增字詞，請參閱「新增字典項目」。

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] 的參照語法，則不需要使用 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。

定義方塊也會顯示編輯按鈕，方便貢獻者編輯詞彙表。

範例

  • 定義方塊：

    已算繪

用量

您可以透過以下幾種方式使用這個小工具：

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 必要
此為必要參數，可避免發生錯誤，但不會執行任何操作。