[xdoctest] reformat example code with google style in `paddle/tensor/math` #55768

SigureMo · 2023-07-28T02:13:49Z

PR types

Others

PR changes

Others

Description

修改如下文件的示例代码为新的格式，并通过 xdoctest 检查：

python/paddle/tensor/math.py

预览：

@sunzhongkai588 @SigureMo @megemini

[xdoctest] 分批次修改已有代码的示例 #55629

PCard-66962

…math`

paddle-bot · 2023-07-28T02:13:53Z

你的PR提交成功，感谢你对开源项目的贡献!
请关注后续CI自动化测试结果，详情请参考Paddle-CI手册。
Your PR has been submitted. Thanks for your contribution!
Please wait for the result of CI firstly. See Paddle CI Manual for details.

paddle-bot · 2023-07-28T02:13:54Z

❌ The PR is not created using PR's template. You can refer to this Demo.
Please use PR's template, it helps save our maintainers' time so that more developers get helped.

SigureMo · 2023-07-28T02:14:50Z

本 PR 用来测试新版的 convert-doctest

另外看看在不同设备是否有「精度」问题

SigureMo · 2023-07-28T02:20:51Z

@megemini

一些小的优化点

最后增加 error summary，不然不太清楚都有哪些挂了，比如这个文件 6000 行，在一堆 SUCCESS 里很难看到哪里有报错，包括运行失败、输出对比失败以及我看有时候还会有 parse error

其实是有的不应该用 .. code-block: python 的错误写成了 python
其他的问题之后再看

megemini · 2023-07-28T05:03:08Z

最后增加 error summary

使用 doctester 的 print_summary 最后输出信息
megemini/convert_doctest@75f3c22

另外，输出信息里面有 line number 可以做个简单的参考吧～

不过，这都是小事儿，刚发现个问题，xdoctest 会把 DoctestParseError 直接 pass 掉 ... ...

        # Always warn when something bad is happening.
        # However, dont error if the docstr simply has bad syntax
        print('msg = {}'.format(msg))
        warnings.warn(msg)
        if isinstance(ex, exceptions.MalformedDocstr):
            pass
        elif isinstance(ex, exceptions.DoctestParseError):
            pass
        else:
            raise

从而导致咱们的 Xdoctester 捕获不到结果，返回的是 nocode=True，也就是没结果：

[TestResult(name='Test docstring from: file *test_math_target.py* line number *591*.', nocode=True, passed=False, skipped=False, failed=False, time=-1, test_msg='', extra_info=None)]

这个咱们在 review 的时候要注意一下... ...

SigureMo · 2023-07-28T05:07:03Z

不过，这都是小事儿，刚发现个问题，xdoctest 会把 DoctestParseError 直接 pass 掉 ... ...

啊这，从 TestResult 好像完全看不出来是解析失败啊……xdoctest 好歹返回一个状态啊……

SigureMo · 2023-07-28T05:07:33Z

另外，输出信息里面有 line number 可以做个简单的参考吧～

嗯嗯，稍后我用新版再尝试几个，看是否还有别的优化点～

SigureMo · 2023-07-28T07:07:51Z

@megemini 果然有部分在本地和 CI 上有部分精度 diff 的，请问精度 diff 有什么比较好的处理方式嘛？直接忽略数值？前后包裹 # doctest: +SKIP # doctest: -SKIP？还是有什么比较好的方式嘛？

megemini · 2023-07-28T07:45:51Z

还是有什么比较好的方式嘛？

不建议 skip ～

这个问题其实有多种解决办法：

python 官方的 doctest 中建议使用更 safer 的方法输出，比如 round
使用 ... ，如：
xdoctest 如果能引入 float 比对的方法是最好的，比如 pytest 就有 https://pypi.org/project/pytest-doctestplus/#floating-point-comparison

pytorch 的 round 已经可以设置保留小数了，paddle 的好像还不行？提个 PR ？

回到此次任务本身，可以考虑转为 numpy 进行 round 输出：

这是在什么设备上导致的问题？影响面大吗？我个人觉得，如果影响面不大，或者只是个别设备的话，可以针对这种设备赦免测试～

你看咋整？！

SigureMo · 2023-07-28T08:51:58Z

pytorch 的 round 已经可以设置保留小数了，paddle 的好像还不行？提个 PR ？

涉及到 API 的变动还是挺麻烦的

xdoctest 如果能引入 float 比对的方法是最好的，比如 pytest 就有 pypi.org/project/pytest-doctestplus/#floating-point-comparison

这个看起来确实是最好的，directive 可以自定义嘛，可以自己写一个嘛？有什么接口嘛？如果可以自定义我觉得是最好的～

这是在什么设备上导致的问题？影响面大吗？我个人觉得，如果影响面不大，或者只是个别设备的话，可以针对这种设备赦免测试～

也可以从 CI 上 copy 结果，但我觉得不是很好

这个设备的话，我是 M1 mac，和你都是 1.94591010，而 CI 上是 1.94591022

megemini · 2023-07-28T10:09:40Z

这个看起来确实是最好的，directive 可以自定义嘛，可以自己写一个嘛？有什么接口嘛？如果可以自定义我觉得是最好的～

这个 ... ... 还得再看看～

我觉得目前可能还真得手动 copy ，其他的几个办法（用 ... 或者用 round）都不太好 ... ...

要么在 issue 里面写个注意事项？

SigureMo · 2023-07-29T10:20:51Z

关于 float 输出匹配，我大致看了 https://stackoverflow.com/questions/2428618/how-to-test-floats-results-with-doctest 里的几个方案，其中 https://github.com/boisgera/numtest 是比较合适的方案，看起来是利用 monkey patch 将 doctest 的 OutputChecker 替换掉了，我们是否也能将 xdoctest 的检查代码（也许是这里？https://github.com/Erotemic/xdoctest/blob/main/src/xdoctest/checker.py#L201 ）替换一下以实现 float 的匹配呢？

大致看了下 PyTorch，没发现使用什么特殊的 directive，不太清楚他们是怎么避免这个问题的，还是说他们没有设备之间计算精度的差异？

megemini · 2023-07-30T11:24:07Z

#55811

已修改～

不过，这种打补丁的方式真的不太好... ...

numtest 相对好一点，应为 python 的 doctest 有 doctest.register_optionflag("NUMBER") 接口，而 xdoctest 没有，只能硬打补丁，从而导致一个问题：

这里只是 patch checker.check_output 方法，如果这个方法出错了，外面错误信息不会显示 patch 之后的字符串，给调试带来不方便，如：

在 checker.check_output 方法中将 1.23456 改为了 1.23457，一旦出错，错误信息还是显示 1.23456 而不是修改后的 1.23457。

megemini

LGTM ~

修改本身没啥问题，但是，好像 renorm 的中文文档没有～
英文有：
http://preview-paddle-pr-55768.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/en/api/paddle/renorm_en.html

中文没有～

另外，中英文文档好像不少对不上，英文的：

中文的：

这只是一少部分～

sunzhongkai588

示例代码存在问题：

nansum @SigureMo 修改下缩进

@sunzhongkai588 文档本身存在问题：

scale
logaddexp
renorm（无中文文档）
increment（中文typo）
frexp（英文return格式）

sunzhongkai588 · 2023-08-07T07:46:33Z

python/paddle/tensor/math.py

+            >>> # scale with parameter scale as a Tensor
+            >>> import paddle

-            data = paddle.randn(shape=[2, 3], dtype='float32')
-            factor = paddle.to_tensor([2], dtype='float32')
-            res = paddle.scale(data, scale=factor, bias=1.0)
+            >>> data = paddle.arange(6).astype("float32").reshape([2, 3])
+            >>> print(data)
+            Tensor(shape=[2, 3], dtype=float32, place=Place(cpu), stop_gradient=True,
+            [[0., 1., 2.],
+             [3., 4., 5.]])
+            >>> factor = paddle.to_tensor([2], dtype='float32')
+            >>> res = paddle.scale(data, scale=factor, bias=1.0)
+            >>> print(res)
+            Tensor(shape=[2, 3], dtype=float32, place=Place(cpu), stop_gradient=True,
+            [[1. , 3. , 5. ],
+             [7. , 9. , 11.]])


这部分中文好像没有copy-from来着，我记一下叭

sunzhongkai588 · 2023-08-07T08:00:47Z

python/paddle/tensor/math.py

@@ -703,7 +726,7 @@ def logaddexp(x, y, name=None):



中文公式好像出了点问题..我记下

sunzhongkai588 · 2023-08-07T10:01:07Z

python/paddle/tensor/math.py

@@ -919,14 +948,16 @@ def remainder(x, y, name=None):

    Examples:



remainder 这个api文档在预览里没找着..但我看__all__是有的呀

我记得 remainder 好像是另一个叫啥 API 的一个 alias（忘了是哪个了），也许和这个有关系

sunzhongkai588 · 2023-08-07T13:01:04Z

python/paddle/tensor/math.py

+                        >>> import paddle
+
+            >>> # x is a Tensor with following elements:


缩进有些问题，改一下吧

Suggested change

>>> import paddle

>>> # x is a Tensor with following elements:

>>> import paddle

>>> # x is a Tensor with following elements:

而且中文的好像也没copy from成功，也是因为缩进么？

就这一个的话我借一个 PR 改一下～

sunzhongkai588 · 2023-08-07T13:10:47Z

python/paddle/tensor/math.py

@@ -2156,17 +2290,19 @@ def renorm(x, p, axis, max_norm):
        Tensor: the renorm Tensor.

    Examples:
-        ..  code-block:: python
+        .. code-block:: python


记一下：补充中文文档

[xdoctest] reformat example code with google style in `paddle/tensor/…

7cf5487

…math`

SigureMo changed the title ~~[xdoctest] reformat example code with google style in `paddle/tensor/…~~ [WIP][xdoctest] reformat example code with google style in paddle/tensor/math Jul 28, 2023

SigureMo mentioned this pull request Jul 28, 2023

[xdoctest] 分批次修改已有代码的示例 #55629

Closed

preview, test=docs_preview

8472b24

SigureMo added 7 commits August 4, 2023 10:22

Merge branch 'develop' into xdoctest/tensor-math

735d4d5

scale, test=docs_preview

818bb4e

stanh, test=docs_preview

4649d4b

multiplex, test=docs_preview

321aa97

pow, test=docs_preview

164c98c

max, test=docs_preview

c6140ea

others..., test=docs_preview

519f121

SigureMo changed the title ~~[WIP][xdoctest] reformat example code with google style in paddle/tensor/math~~ [xdoctest] reformat example code with google style in paddle/tensor/math Aug 5, 2023

update trunc example code, test=docs_preview

66a68dd

megemini approved these changes Aug 6, 2023

View reviewed changes

luotao1 approved these changes Aug 7, 2023

View reviewed changes

luotao1 merged commit ae88111 into PaddlePaddle:develop Aug 7, 2023

SigureMo deleted the xdoctest/tensor-math branch August 7, 2023 08:26

sunzhongkai588 reviewed Aug 8, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[xdoctest] reformat example code with google style in `paddle/tensor/math` #55768

[xdoctest] reformat example code with google style in `paddle/tensor/math` #55768

SigureMo commented Jul 28, 2023 •

edited

Loading

paddle-bot bot commented Jul 28, 2023

paddle-bot bot commented Jul 28, 2023

SigureMo commented Jul 28, 2023 •

edited

Loading

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023 •

edited

Loading

SigureMo commented Jul 28, 2023

SigureMo commented Jul 28, 2023

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023

SigureMo commented Jul 29, 2023

megemini commented Jul 30, 2023 •

edited

Loading

megemini left a comment

sunzhongkai588 left a comment •

edited

Loading

sunzhongkai588 Aug 7, 2023

sunzhongkai588 Aug 7, 2023

sunzhongkai588 Aug 7, 2023

SigureMo Aug 8, 2023

sunzhongkai588 Aug 7, 2023

SigureMo Aug 8, 2023

sunzhongkai588 Aug 7, 2023

		@@ -919,14 +948,16 @@ def remainder(x, y, name=None):

		Examples:

		>>> import paddle

		>>> # x is a Tensor with following elements:

[xdoctest] reformat example code with google style in paddle/tensor/math #55768

[xdoctest] reformat example code with google style in paddle/tensor/math #55768

Conversation

SigureMo commented Jul 28, 2023 • edited Loading

PR types

PR changes

Description

paddle-bot bot commented Jul 28, 2023

paddle-bot bot commented Jul 28, 2023

SigureMo commented Jul 28, 2023 • edited Loading

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023 • edited Loading

SigureMo commented Jul 28, 2023

SigureMo commented Jul 28, 2023

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023

SigureMo commented Jul 28, 2023

megemini commented Jul 28, 2023

SigureMo commented Jul 29, 2023

megemini commented Jul 30, 2023 • edited Loading

megemini left a comment

Choose a reason for hiding this comment

sunzhongkai588 left a comment • edited Loading

Choose a reason for hiding this comment

sunzhongkai588 Aug 7, 2023

Choose a reason for hiding this comment

sunzhongkai588 Aug 7, 2023

Choose a reason for hiding this comment

sunzhongkai588 Aug 7, 2023

Choose a reason for hiding this comment

SigureMo Aug 8, 2023

Choose a reason for hiding this comment

sunzhongkai588 Aug 7, 2023

Choose a reason for hiding this comment

SigureMo Aug 8, 2023

Choose a reason for hiding this comment

sunzhongkai588 Aug 7, 2023

Choose a reason for hiding this comment

[xdoctest] reformat example code with google style in `paddle/tensor/math` #55768

[xdoctest] reformat example code with google style in `paddle/tensor/math` #55768

SigureMo commented Jul 28, 2023 •

edited

Loading

SigureMo commented Jul 28, 2023 •

edited

Loading

megemini commented Jul 28, 2023 •

edited

Loading

megemini commented Jul 30, 2023 •

edited

Loading

sunzhongkai588 left a comment •

edited

Loading