【Type Hints】将 typehints 显示在描述中而不是函数签名中

PR Category

User Experience

PR Types

Improvements

Description

将 typehints 显示在描述中，而不是函数签名中～

建议：

在中文文档中不要写 type 。目前 torch、tf、keras 等，均没有在文档中的函数签名中写 type。
在 api 的 docstring 中需要写类型

以本 PR 中的 api paddle.audio.save 为例，原 api 代码中：

增加 from __future__ import annotations
Optional 改为 |
docstring 中增加数据类型

def save(
    filepath: str,
    src: paddle.Tensor,
    sample_rate: int,
    channels_first: bool = True,
    encoding: Optional[str] = None,
    bits_per_sample: Optional[int] = 16, # 注：此处不应该使用 Optional
):
    """
    Save audio tensor to file.

    Args:
        filepath: ...
        src: ...
        sample_rate: ...
        channels_first: ...
        encoding: ...
        bits_per_sample: ...

    Returns:
        None
...
    """

需要改为：

from __future__ import annotations
...
def save(
    filepath: str,
    src: paddle.Tensor,
    sample_rate: int,
    channels_first: bool = True,
    encoding: str|None = None,
    bits_per_sample: int = 16,
) -> None:
    """
    Save audio tensor to file.

    Args:
        filepath (str): ...
        src (Tensor): ...
        sample_rate (int): ...
        channels_first (bool, optional): ...
        encoding (str|None, optional): ...
        bits_per_sample (int, optional): ...

    Returns:
        None
...
    """

此 api 的中文文档中，需要修改：

签名中不写 type

.. py:function:: paddle.audio.save(filepath: str, src: paddle.Tensor, sample_rate: int, channels_first: bool = True, encoding: Optional[str] = None, bits_per_sample: Optional[int] = 16)

需要改为

.. py:function:: paddle.audio.save(filepath, src, sample_rate, channels_first=True, encoding=None, bits_per_sample=16)

修改后，原中文文档的页面：

变更为：

原英文文档的页面：

变更为：

注意：此时还未修改此 api 的 docstring，英文文档中，描述中的参数类型，是 sphinx 自动加进去的～

但是，如果修改了 api 的 docstring，添加了数据类型，sphinx 理论上会 merge 函数签名中的类型与描述中的参数类型～因此，此处具体效果还需要后续观察～

@sunzhongkai588 @SigureMo

PaddlePaddle / docs

【Type Hints】将 typehints 显示在描述中而不是函数签名中 #6676

PR Category

PR Types

Description