Closed megemini closed 2 months ago
User Experience
Improvements
将 typehints 显示在描述中,而不是函数签名中 ~
建议:
以本 PR 中的 api paddle.audio.save 为例,原 api 代码中:
paddle.audio.save
from __future__ import annotations
|
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 的中文文档中,需要修改:
.. 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
感谢你贡献飞桨文档,文档预览构建中,Docs-New 跑完后即可预览,预览链接:http://preview-pr-6676.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html 预览工具的更多说明,请参考:飞桨文档预览工具
PR Category
User Experience
PR Types
Improvements
Description
将 typehints 显示在描述中,而不是函数签名中 ~
建议:
以本 PR 中的 api
paddle.audio.save
为例,原 api 代码中:from __future__ import annotations
|
需要改为:
此 api 的中文文档中,需要修改:
需要改为
修改后,原中文文档的页面:
变更为:
原英文文档的页面:
变更为 :
注意:此时还未修改此 api 的 docstring,英文文档中,描述中的参数类型,是 sphinx 自动加进去的 ~
但是,如果修改了 api 的 docstring,添加了数据类型,sphinx 理论上会 merge 函数签名中的类型与描述中的参数类型 ~ 因此,此处具体效果还需要后续观察 ~
@sunzhongkai588 @SigureMo