添加引用

文档中的类型引用

为了正确渲染，请始终使用正确的 角色 来指定类型（参见 https://sphinx-doc.cn/en/1.7/domains.html#python-roles）。例如：使用 :class:`int` 来指代 int 类型，通常使用 :class:`<path>`​ 来指代某个类（参见下面的 路径 规范）。更多具体说明请参见下文。

路径规范

  1. 如果它在标准库中：直接使用 <name>。如果是类，只需名称即可。如果是方法 (:meth:) 或属性 (:attr:)，可以使用点分名称（例如 :meth:`str.to_lower`​）。

示例：:class:`int`​, :class:`str`​, :class:`float`​, :class:`bool`​

  1. 如果它与文档字符串在同一文件中，或者对于方法和属性，在同一类下，则也可以直接指定名称。

示例：:class:`MyClass`​ 指代同一文件中的类；:meth:`push`​ 指代同一类中的方法；:meth:`MyClass.push`​ 指代同一文件中不同类中的方法；:attr:`color`​ 指代同一类中的属性；:attr:`MyClass.color`​ 指代同一文件中不同类中的属性。

  1. 如果它在不同的文件中，那么您可以使用完整的点分名称（例如 ~manim.animations.Animation）或仅使用缩写方式（~.Animation）。请注意，如果存在歧义，则必须使用完整的点分名称，以防实际类无法推断。此外，请注意路径前的 ~——这是为了在渲染时只显示 Animation 而不是完整位置。仅出于消歧目的可以将其移除。

示例：:class:`~.Animation`​, :meth:`~.VMobject.set_color`​, :attr:`~.VMobject.color`​

  1. 如果它是来自不同模块的类，请指定完整的点分语法。

示例：:class:`numpy.ndarray`​ 用于 numpy ndarray。

引用类型规范

以下说明指的是属性、参数和返回值的类型。 在文本中指定类型时，不一定需要排版。但是，如果它是类名、方法或枚举的属性/变体，则建议至少在名称第一次出现时进行排版，以便用户可以快速跳转到相关文档。

  1. 类名应包含在 :class:`path_goes_here`​ 中。参见上一小节中的示例。

  2. 方法名应包含在 :meth:`path_goes_here`​ 中。参见上一小节中的示例。

  3. 属性名应包含在 :attr:`path_goes_here`​ 中。参见上一小节中的示例。

  4. 如果也可以指定 None，请使用 Optional[type]，其中 type 必须遵循本节中的指导原则。

示例：Optional[:class:`str`] 意味着您可以指定 str 或 None。

  1. 如果可能存在多种类型，请使用 Union[type_1, type_2, (...), type_n]，其中所有 type_n 都必须遵循本节中的指导原则。请注意，如果其中一种类型是 None，则 Union 应改用 Optional 包装。

示例：Union[:class:`str`, :class:`int`] 表示 str 或 int。Optional[Union[:class:`int`, :class:`bool`]] 表示 int、bool 或 None。

  1. 字典： 使用 Dict[key_type, value_type]，其中 key_type 和 value_type 必须遵循本节中的指导原则。

示例：Dict[:class:`str`, :class:`~.Mobject`] 是一个将字符串映射到 Mobject 的字典。Dict[:class:`str`, Union[:class:`int`, :class:`MyClass`]] 是一个将字符串映射到 int 或 MyClass 实例的字典。

  1. 如果参数是列表： 请注意，很少需要参数严格为 list 类型。例如，通常可以指定 tuple。因此，为了涵盖所有情况，请考虑：

    1. 如果参数只需要是 Iterable，即函数只需要能够遍历此参数的值（例如可以是 list、tuple、str，也可以是 zip()、iter() 等），则指定 Iterable[type_here]，其中 type_here 是可迭代对象生成的元素的类型，并应遵循本节（类型 规范）中的格式。

    示例：Iterable[:class:`str`] 用于任何字符串可迭代对象；Iterable[:class:`~.Mobject`] 用于 Mobject 可迭代对象；等等。

    1. 如果您需要能够索引参数（即 x[n]）或获取其长度（即 len(x)），甚至只是将其传递给需要这些操作的函数，则指定 Sequence，它允许指定任何类列表对象（例如 list、tuple…）

    示例：Sequence[:class:`str`] 用于字符串序列；Sequence[Union[:class:`str`, :class:`int`]] 用于整数或字符串序列。

    1. 如果由于某种原因您明确要求它是 list，则使用 List[type]，其中 type 是列表中任何元素的类型。它必须遵循本节中的指导原则。

  2. 如果返回类型是列表或元组： 列表指定 List[type]，元组指定 Tuple[type_a, type_b, (...), type_n]（如果元素都不同）或 Tuple[type, ...]（如果所有元素类型相同）。这些表示中的每个 type_n 都对应于返回列表/元组中的元素，并且必须遵循本节中的指导原则。

示例：List[Optional[:class:`str`]] 表示返回元素为 str 或 None 的列表；Tuple[:class:`str`, :class:`int`] 表示类型为 (str, int) 的元组；Tuple[:class:`int`, ...] 表示可变长度且只包含整数的元组。