添加文档字符串¶

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

格式化文档字符串¶

请在三个引号的同一行开始类/函数的描述：

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


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

NumPy 格式¶

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

使用numpy格式进行章节和格式化 - 参见 https://numpydoc.readthedocs.io/en/latest/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来指定每个参数的工作方式及其作用。如果函数没有参数，则应排除此部分。请注意，您不应在类型上指定参数的默认值。在文档渲染中，这已经在函数的签名中指定。如果您需要指出值省略的进一步后果，或者只是想在文档中指定它，请确保在参数的DESCRIPTION中指定它。

查看列表项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
----------------
kwarg_param_1
  Parameter documentation here
(etc)

使用Returns来指示此函数的返回值类型以及它具体返回什么（即，如果需要，可以简短或详细描述此函数返回的内容）。如果函数没有明确返回（即，因为从未指定return，所以总是返回None，并且非常清楚为什么此函数根本不返回），则可以省略。在所有其他情况下，应指定。

请查看列表项4上的示例。

强烈建议使用示例来指定函数的使用示例，并且通常应为每个函数指定，除非其用法极其明显，这可能有争议。即使如此，添加一个示例以更好地指导文档用户始终是一个好主意。使用以下格式编写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