标签指南#

为什么我们需要标签?#

标签有多种用途.

标签具有一对多的组织结构(即,一个示例可以有多个标签),而图库结构要求示例仅放置在一个位置.这意味着标签提供了第二层组织结构,并使示例图库更灵活,更用户友好.

它们可以实现更好的可发现性,搜索和浏览功能.它们对难以编写搜索查询的用户很有帮助.

隐藏标签为维护者和贡献者提供了其他功能.

如何打标签?#

将标签指令放在每个页面的底部,并在下面添加标签,例如:

.. tags::
   topic: tagging, purpose: reference

什么内容需要打标签?#

每个图库示例都应标记:

  • 1+ 内容标签

  • 如果适用,则添加结构,域或内部标签

标签可以重复现有的组织形式(例如,一个示例在"动画"文件夹中,并且还具有一个 animation 标签).

标签有助于表示特别好的"副产品"示例.例如,图库示例的明确目的可能是演示色彩图,但它也是图例的良好演示.标记 legend 以指示这一点,而不是更改示例的标题或范围.

标签类别

有关完整列表,请参见 Tag Glossary

提议新标签#

  1. 查看现有标签列表,留意相似的条目(即 axes 和 axis ).

  2. 如果相关的标签或子类别尚不存在,请提出它.每个标签分为两部分: subcategory: tag .标签应为一个或两个单词.

  3. 当新标签也与现有图库条目相关时,应添加它们.避免仅链接到单个图库条目的标签.

  4. 标签可以重新创建其他组织形式.

标签组织旨在适用于 80-90％ 的情况.某些示例不属于标签结构.不应为利基或特定示例提供不适用于其他示例的独立标签.

On this page