添加文档字符串¶

文档字符串是一种字符串字面量，用于模块、函数、类或方法定义之后。它们用于为我们的代码编写文档。本页将为您提供一套编写高效且正确的文档字符串的指南。

文档字符串格式化¶

请在与三个引号同行的位置开始编写类/函数的描述

def do_this():
    """This is correct.
    (...)
    """


def dont_do_this():
    """
    This is incorrect.
    (...)
    """

NumPy格式¶

Manim社区使用NumPy格式进行文档编写。

使用NumPy格式来编写章节和进行格式化 - 详见https://numpydoc.readthedocs.io/en/stable/format.html。

这包括

使用Attributes来指定一个类可以拥有的所有属性，并提供简短（或必要时详细）的描述。

此外，`__init__`参数应在**类文档字符串中**指定为Parameters，而不是在__init__下方。请注意，如果参数和属性相同（即数据类），则可以省略此项——在这种情况下，应优先使用Attributes部分，该部分**必须始终存在**，除非该类完全没有指定任何属性。（有关参数的更多信息，请参阅此列表的第2条。）

示例

class MyClass:
    """My cool class. Long or short (whatever is more appropriate) description here.

    Parameters
    ----------
    name
        The class's name.
    id
        The class's id.
    mobj
        The mobject linked to this instance. Defaults to `Mobject()` \
(is set to that if `None` is specified).

    Attributes
    ----------
    name
        The user's name.
    id
        The user's id.
    singleton
        Something.
    mobj
        The mobject linked to this instance.
    """

    def __init__(name: str, id: int, singleton: MyClass, mobj: Mobject = None): ...

在函数上使用Parameters来指定每个参数的工作方式和作用。如果函数没有参数，则应省略此项。请注意，您**不应**在类型上指定参数的默认值。在文档渲染时，这已在函数的签名中指定。如果您需要指出省略值的进一步后果，或者只是想在文档中指定它，请务必在**参数的描述中指定**。

请参阅列表项4中的示例。

注意

在编写可变参数（args和kwargs）的文档时，请确保通过列出每个指定值的可能类型来记录它们，如下所示

Parameters
----------
args
  The args specified can be either an int or a float.
kwargs
  The kwargs specified can only be a float.

请注意，如果kwargs需要特定值，这些值可以在Other Parameters等部分中指定。

Other Parameters
----------------
kwarg_param_1
  Parameter documentation here
(etc)

使用Returns来指示此函数的返回值类型以及它具体返回什么（即，对该函数返回的内容进行简短或必要时详细的描述）。如果函数没有显式返回（即，始终返回None，因为从未指定return，并且该函数不返回任何内容的原因非常清楚），则可以省略此项。在所有其他情况下，都应指定它。

请参阅列表项4中的示例。

强烈建议**使用Examples来提供函数使用示例，并且通常应为*每个函数*指定，除非其用法**极其明显**，但这可能存在争议。即使如此，添加一个示例始终是一个好主意，以便更好地指导文档用户。Python代码请使用以下格式
```
::

# python code here
```

注意

此外，如果这是与视频或动画相关的更改，请尽可能添加示例GIF或视频以供演示。

请确保您的文档尽可能明确。我们都希望用户能更轻松地使用此库。

示例

def my_function(
    thing: int,
    other: np.ndarray,
    name: str,
    *,
    d: "SomeClassFromFarAway",
    test: Optional[int] = 45
) -> "EpicClassInThisFile":  # typings are optional for now
    """My cool function. Builds and modifies an :class:`EpicClassInThisFile` instance with the given
        parameters.

    Parameters
    ----------
    thing
        Specifies the index of life.
    other
        Specifies something cool.
    name
        Specifies my name.
    d
        Sets thing D to this value.
    test
        Defines the number of times things should be tested. \
    Defaults to 45, because that is almost the meaning of life.

    Returns
    -------
    :class:`EpicClassInThisFile`
        The generated EpicClass with the specified attributes and modifications.

    Examples
    --------
    Normal usage::

        my_function(5, np.array([1, 2, 3]), "Chelovek", d=SomeClassFromFarAway(cool=True), test=5)
    """
    # code...
    pass