polish pytorch api mapping format (#5780)

Author: zhwesky2010

docs/guides/model_convert/convert_from_pytorch/api_difference/Tensor/torch.Tensor.where.md

@@ -1,4 +1,4 @@
-## [参数用法不⼀致]torch.Tensor.where
+## [ 参数不⼀致 ]torch.Tensor.where
 
 ### [torch.Tensor.where](https://pytorch.org/docs/1.13/generated/torch.Tensor.where.html#torch.Tensor.where)
 

docs/guides/model_convert/convert_from_pytorch/api_difference/functional/torch.nn.functional.pad.md

@@ -1,4 +1,4 @@
-## [ 仅 paddle 参数更多 ]torch.nn.functional.one_hot
+## [ 仅 paddle 参数更多 ]torch.nn.functional.pad
 
 ### [torch.nn.functional.pad](https://pytorch.org/docs/stable/generated/torch.nn.functional.pad.html)
 

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.chunk.md

@@ -1,4 +1,4 @@
-## [仅参数名不同]torch.chunk
+## [ 仅参数名不同 ]torch.chunk
 ### [torch.chunk](https://pytorch.org/docs/stable/generated/torch.chunk.html?highlight=chunk#torch.chunk)
 
 ```python

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.is_floating_point.md

@@ -1,4 +1,5 @@
 ## [ 仅参数名不一致 ]torch.is_floating_point
+
 ### [torch.is_floating_point](https://pytorch.org/docs/stable/generated/torch.is_floating_point.html?highlight=is_floating_point#torch.is_floating_point)
 
 ```python

docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.transpose.md

@@ -1,4 +1,4 @@
-## [参数用法不⼀致] torch.transpose
+## [ 参数不⼀致 ] torch.transpose
 
 ### [torch.transpose](https://pytorch.org/docs/stable/generated/torch.transpose.html?highlight=transpose#torch.transpose)
 

docs/guides/model_convert/convert_from_pytorch/api_difference/pytorch_api_mapping_format_cn.md

@@ -1,21 +1,23 @@
-# API 映射关系 - 格式规范
-
 > 提交代码前请参考[官网](https://www.paddlepaddle.org.cn/documentation/docs/zh/dev_guides/code_contributing_path_cn.html)安装 `pre-commit`，规范化代码格式。
 
-需严格根据此模板的格式规范来新增《API 映射关系》，具体如下:
+请严格根据此格式规范来新增《API 映射关系》，不符合规范的文档将不予合入，具体如下:
+
+# API 映射关系 - 格式规范
 
 ### [分类名称] api 全称
 
-为了文档整体的一致性，我们统一了分类名称，分类名称需和下面保持一致。共分为 7 大类：
+为了文档整体的一致性，我们统一了 API 映射关系的分类名称，共分为 7 大类：
+> 注：第 1~3 类均为 API 层面一对一映射，根据参数层面的映射关系将其细分为三类。
 
-* 其中第１类又分为五种情况：`无参数`、`参数完全一致`、`仅参数名不一致`、`仅 paddle 参数更多`、`仅参数默认值不一致`。分类优先级依次递增，即如果同时 `参数名不一致` + `paddle 参数更多`，则写成后者 `仅 paddle 参数更多` 。
+* 第 1 类又分为五种情况：`无参数`、`参数完全一致`、`仅参数名不一致`、`仅 paddle 参数更多`、`仅参数默认值不一致`。
+> 注：分类优先级依次递增，即如果同时 `参数名不一致` + `paddle 参数更多`，则写成后者 `仅 paddle 参数更多` 。
 
-* 第２类为 `torch 参数更多`。如果 torch 和 paddle 都支持更多参数，统一写成`torch 参数更多`。
+* 第 2 类为 `torch 参数更多`。如果 torch 和 paddle 都支持更多参数，统一写成`torch 参数更多`。
 
-* 第３类为 `参数不一致`。包括不限于 输入参数支持类型不一致、输入参数用法不一致、返回参数类型不一致 等情况。
+* 第 3 类为 `参数不一致`。包括不限于 输入参数支持类型不一致、输入参数用法不一致、返回参数类型不一致 等情况。
 > 注意：这里的一致都是从 torch 的角度来看，如果 paddle 可涵盖 torch，即 torch 是 paddle 的功能子集，即认为是一致。例如：torch 参数仅支持 list，paddle 参数支持 list/tuple，则认为两者一致。反之则不一致。
 
-* 第４类为 `组合替代实现` ，表示该 API 没有可直接对应的 API，需要通过多个 API 组合实现。
+* 第 4 类为 `组合替代实现` ，表示该 API 没有可直接对应的 API，需要通过多个 API 组合实现。
 
 * 第 5 类为 `用法不同：涉及上下文修改` ，表示涉及到上下文分析，需要修改其他位置的代码。
 > 举例：所有的 `torch.optim.lr_scheduler.*`、`torch.nn.init.*`、`torch.nn.utils.clip*` 都为该类。主要由于设计上与 Paddle 具有较大的差异，需要对上文例如 Layer 的`weight_attr`进行设置，涉及到上文代码联动修改。
@@ -27,26 +29,39 @@
 > 注意：
 > 1. 分类优先级依次递增，即如果同时 `第 2 类：torch 参数更多` 与 `第 3 类：参数不一致` ，则写成后者 `第 3 类：参数不一致` 。
 > 2. 所有的 Paddle API 无需关注 `name` 参数，直接忽略即可。
+> 3. 将类成员 API 映射为非类成员 API，则无需对比第一个参数。例如将 `torch.Tensor.outer(vec2)` 映射为 `paddle.outer(x, y)`，则忽略 paddle 的第一个参数，从 torch 的 `vec2` 和 paddle 的 `y` 开始对比。
 
 ### [pytorch api 全称] (pytorch api 链接)
 
+```python
+Pytorch API 签名
+```
+
 ### [paddle api 全称] (paddle api 链接)
 
+```python
+Paddle API 签名
+```
+
 **一句话总结**。整体概述总结两个 API 的差异。例如 `第 3 类：参数不一致` ，需要简述下有哪些不一致的地方。在描写参数时，需要用 \` ` 来加深其底色。
 
 ### 参数映射
 
 参数映射表的左边是`PyTorch` 对应参数，右边是`Paddle`对应参数，表格参数顺序按 `PyTorch` 参数顺序来。
 
-* 如果仅参数名不一致，需要在备注栏加一句 `仅参数名不一致`。
+* 如果 `仅参数名不一致`，需要在备注栏里对该参数加一句 `仅参数名不一致`。
+
+* 如果 `仅 paddle 参数更多`，需要在备注栏加一句 `PyTorch 无此参数` + `Paddle 应如何设置此参数` 。如果默认无影响，则写 `PyTorch 无此参数， Paddle 保持默认即可`。
 
-* 如果 paddle 参数更多，需要在备注栏加一句`PyTorch 无此参数` + `Paddle 应如何设置此参数` 。如果默认无影响，则写 `PyTorch 无此参数， Paddle 保持默认即可`。
+* 如果 `仅参数默认值不一致`，需要在备注栏里加一句 `与 Pytorch 默认值不同` + `Paddle 应如何设置此参数` 。
+
+* 对于其他类别，均需要写**转写示例**，如确实无法支持，需要在备注里加一句 `Paddle 暂无转写方式`。
 
 * 每个备注都需要`以句号结尾`。
 
 ### 转写示例
 
-仅第 1 类不需要写转写示例，其他类别均必须写转写示例。
+**除第 1 类 API 对应关系较为简单，无需写转写示例，其他类 API 都需要写转写示例，否则需注明：Paddle 暂无转写方式。**
 
 转写示例需要写得精简和一目了然。一般情形下只需写两行代码，无需打印各种结果，并且要保证转写前后的输出结果是一致的。另外需要先描述下待写的是该 torch api 的哪个参数及其功能。
 
@@ -68,12 +83,29 @@ torch.xxx()
 paddle.xxx()
 ```
 
+---
 # API 映射关系 - 模板
 
 ## 模板 1
 
 ### [ 仅参数名不一致 ] torch.xxx
 
+### [torch.dist](https://pytorch.org/docs/stable/generated/torch.dist.html?highlight=dist#torch.dist)(仅作为示例)
+
+```python
+torch.dist(input,
+           other,
+           p=2)
+```
+
+### [paddle.dist](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/dist_cn.html#dist)(仅作为示例)
+
+```python
+paddle.dist(x,
+            y,
+            p=2)
+```
+
 两者功能一致且参数用法一致，仅参数名不一致，具体如下：
 
 ### 参数映射
@@ -96,6 +128,20 @@ paddle.xxx()
 
 ### [ 仅 paddle 参数更多 ] torch.xxx
 
+### [torch.nn.ZeroPad2d](https://pytorch.org/docs/stable/generated/torch.nn.ZeroPad2d.html?highlight=zeropad#torch.nn.ZeroPad2d)(仅作为示例)
+
+```python
+torch.nn.ZeroPad2d(padding)
+```
+
+### [paddle.nn.ZeroPad2D](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/ZeroPad2D_cn.html)(仅作为示例)
+
+```python
+paddle.nn.ZeroPad2D(padding,
+                    data_format='NCHW',
+                    name=None)
+```
+
 Paddle 相比 PyTorch 支持更多其他参数，具体如下：
 
 ### 参数映射
@@ -108,10 +154,26 @@ Paddle 相比 PyTorch 支持更多其他参数，具体如下：
 | -       | place         | 表示 Tensor 存放位置， PyTorch 无此参数， Paddle 需设置为 paddle.CPUPlace()。 |
 | -       | stop_gradient | 表示是否阻断梯度传导， PyTorch 无此参数， Paddle 保持默认即可。 |
 
+
 ## 模板 3
 
 ### [ torch 参数更多 ] torch.xxx
 
+### [torch.abs](https://pytorch.org/docs/stable/generated/torch.abs.html?highlight=abs#torch.abs)(仅作为示例)
+
+```python
+torch.abs(input,
+          *,
+          out=None)
+```
+
+### [paddle.abs](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/abs_cn.html#abs)(仅作为示例)
+
+```python
+paddle.abs(x,
+           name=None)
+```
+
 Pytorch 相比 Paddle 支持更多其他参数，具体如下：
 
 ### 参数映射
@@ -192,10 +254,27 @@ else:
     reduction = 'none'
 ```
 
+
 ## 模板 4
 
 ### [ 参数不一致 ] torch.xxx
 
+### [torch.transpose](https://pytorch.org/docs/stable/generated/torch.transpose.html?highlight=transpose#torch.transpose)(仅作为示例)
+
+```python
+torch.transpose(input,
+                dim0,
+                dim1)
+```
+
+### [paddle.transpose](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/transpose_cn.html#transpose)(仅作为示例)
+
+```python
+paddle.transpose(x,
+                 perm,
+                 name=None)
+```
+
 Pytorch 的 `tensors` 参数与 Paddle 的 `inputs` 参数用法不同，具体如下：
 
 ### 参数映射
@@ -235,11 +314,12 @@ m = torch.nn.BatchNorm1D(24)
 m = paddle.nn.BatchNorm1D(24)
 ```
 
+
 ## 模板 5
 
 ### [ 组合替代实现 ] torchvision.transforms.ToPILImage
 
-### [torchvision.transforms.ToPILImage](https://pytorch.org/vision/stable/transforms.html?highlight=topilimage#torchvision.transforms.ToPILImage)
+### [torchvision.transforms.ToPILImage](https://pytorch.org/vision/stable/transforms.html?highlight=topilimage#torchvision.transforms.ToPILImage)(仅作为示例)
 
 ```python
 torchvision.transforms.ToPILImage(mode=None)
@@ -356,10 +436,25 @@ class ToPILImage(BaseTransform):
         return Image.fromarray(npimg, mode=self.mode)
 ```
 
+
 ## 模板 6
 
 ### [ 用法不同：涉及上下文修改 ] torch.xxx
 
+### [torch.nn.utils.clip_grad_value_](https://pytorch.org/docs/stable/generated/torch.nn.utils.clip_grad_value_.html?highlight=clip_grad_value_#torch.nn.utils.clip_grad_value_)(仅作为示例)
+
+```python
+torch.nn.utils.clip_grad_value_(parameters,
+                                clip_value)
+```
+
+### [paddle.nn.ClipGradByValue](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/ClipGradByValue_cn.html#clipgradbyvalue)(仅作为示例)
+
+```python
+paddle.nn.ClipGradByValue(max,
+                          min=None)
+```
+
 其中 Pytorch 与 Paddle 对该 API 的设计思路与⽤法不同，需要分析上下⽂并联动修改：
 
 ### 参数映射

docs/guides/model_convert/convert_from_pytorch/pytorch_api_mapping_cn.md

@@ -166,7 +166,7 @@
 | 136   |  [torch.tensor](https://pytorch.org/docs/stable/generated/torch.tensor.html?highlight=tensor#torch.tensor)  |  [paddle.to_tensor](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/to_tensor_cn.html#to-tensor)  |    功能一致, torch 参数更多 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.tensor.md)  |
 | 137   |  [torch.tile](https://pytorch.org/docs/stable/generated/torch.tile.html?highlight=tile#torch.tile)  |  [paddle.tile](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/tile_cn.html#tile)  |    功能一致, 仅参数名不一致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.tile.md)  |
 | 138   |  [torch.trace](https://pytorch.org/docs/stable/generated/torch.trace.html?highlight=trace#torch.trace)  |  [paddle.trace](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/trace_cn.html)  |    功能一致, 仅参数名不一致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.trace.md)  |
-| 139   |  [torch.transpose](https://pytorch.org/docs/stable/generated/torch.transpose.html?highlight=transpose#torch.transpose)  |  [paddle.transpose](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/transpose_cn.html#transpose)  |  功能一致, 参数用法不⼀致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.transpose.md)  |
+| 139   |  [torch.transpose](https://pytorch.org/docs/stable/generated/torch.transpose.html?highlight=transpose#torch.transpose)  |  [paddle.transpose](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/transpose_cn.html#transpose)  |  功能一致, 参数不⼀致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.transpose.md)  |
 | 140   |  [torch.unbind](https://pytorch.org/docs/stable/generated/torch.unbind.html?highlight=unbind#torch.unbind)  |  [paddle.unbind](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/unbind_cn.html#unbind)  |    功能一致, 仅参数名不一致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.unbind.md)  |
 | 141   |  [torch.unique](https://pytorch.org/docs/stable/generated/torch.unique.html?highlight=unique#torch.unique)  |  [paddle.unique](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/unique_cn.html#unique)  |  功能一致, torch 参数更多 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.unique.md)  |
 | 142   |  [torch.unique_consecutive](https://pytorch.org/docs/stable/generated/torch.unique_consecutive.html?highlight=unique_consecutive#torch.unique_consecutive)  |  [paddle.unique_consecutive](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/unique_consecutive_cn.html#unique-consecutive)  |    功能一致, 仅参数名不一致 , [差异对比](https://github.com/PaddlePaddle/docs/tree/develop/docs/guides/model_convert/convert_from_pytorch/api_difference/ops/torch.unique_consecutive.md)  |