标记指南

为什么我们需要标签？

标签有多种用途。

标签具有一对多的组织结构（即一个示例可以有多个标签），而图库结构要求示例只能放置在一个位置。这意味着标签提供了第二层组织结构，使示例图库更加灵活和用户友好。

它们允许更好的可发现性、搜索和浏览功能。对于那些难以写出所需内容的搜索查询的用户来说，它们非常有帮助。

隐藏标签为维护者和贡献者提供了额外的功能。

如何标记？

将标签指令放在每页的底部，并在其下方添加标签，例如：

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

什么会得到标签？

每个图库示例都应标记为：

• 1+ 内容标签

• 结构、领域或内部标签（如果有助于理解）

标签可以重复现有的组织形式（例如，一个示例在Animation文件夹中，并且也获得了一个 animation 标签）。

标签有助于标记特别好的“副产品”示例。例如，图库示例的明确目的是演示色图，但它也是一个很好的图例演示。标记 legend 以表明这一点，而不是更改示例的标题或范围。

标签类别

• 标签术语
  • API 标签：示例中包含 API 参考的哪些内容？
  • 结构标签：示例是什么格式？我们可以提供什么上下文？
  • 领域标签：哪些学科可能会持续寻求这个示例？
  • 内部标签：哪些信息对维护者或贡献者有帮助？

查看 标签词汇表 以获取完整列表

提议新标签

1. 审查现有的标签列表，注意相似的条目（例如 axes 和 axis）。

2. 如果尚不存在相关的标签或子类别，请提出建议。每个标签由两部分组成：子类别: 标签。标签应为一个或两个词。

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

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

标签化组织的目的是为80-90%的情况工作。一些例子超出了标签化结构。小众或特定的例子不应被赋予不会适用于其他例子的独立标签。