[Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 #6096

megemini · 2023-08-14T10:50:47Z

PR types

Others

PR changes

Docs

Description

中国软件开源创新大赛：飞桨框架任务挑战赛
赛题五：将 xdoctest 引入到飞桨框架工作流中

RFC [Add]将 xdoctest 引入到飞桨框架工作流中v1
ISSUE 赛题五：将 xdoctest 引入到飞桨框架工作流中 Tracking Issue

第二阶段
任务：更新文档《开发 API Python 端》与《API 文档书写规范》

涉及文件：

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md 修改 API 代码示例部分。
docs/dev_guides/api_contributing_guides/images/zeros_python_api.png 修改示例图片为修改后的样式。

@SigureMo @luotao1 @jzhang533 @sunzhongkai588

请评审，谢谢！：）

paddle-bot · 2023-08-14T10:50:52Z

感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-6096.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明，请参考：飞桨文档预览工具

SigureMo

示例代码的篇幅可能太多了，之后需要看一下预览具体占据多少篇幅，如果篇幅过多，则应该单独成篇，或者以附录那种形式，不然会影响其他部分的阅读

SigureMo · 2023-08-14T10:55:58Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+
+因此，请在书写示例代码时遵循以下规范：
+
+1. **显性的输出好于注释**


Suggested change

1. **显性的输出好于注释**

1. **显式的输出好于注释**

SigureMo · 2023-08-14T10:56:41Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+
+1. **显性的输出好于注释**
+
+    请使用 `print` 输出变量的结果。


print 可能不是必要的？

SigureMo · 2023-08-14T10:57:33Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+    # [[5 , 12],
+    #  [21, 32]]


Suggested change

# [[5 , 12],

# [21, 32]]

>>> # [[5 , 12],

>>> # [21, 32]]

这里是不是指这样子的？因为原来的 CI 肯定会挂的

SigureMo · 2023-08-14T10:57:57Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+
+    等，都是不建议的输出方式。
+
+    另外，在 书写/拷贝 示例代码时，请注意以下几点：


书写/拷贝两侧不要加空格

SigureMo · 2023-08-14T12:00:46Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+        >>> ...
+        ```
+
+    请注意这里的 **大小写** ！


正式文档里最好不要加这种语气词、语气符号？

SigureMo · 2023-08-14T12:01:53Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+
+4. **能够检查好于跳过检查**
+
+    示例代码的检查可以保证其正确性，但并不是所有代码均能够 正常/正确 的在 CI 环境中运行。


这里正常/正确也一样，最好不要加空格，如果是强调，可以用 **

SigureMo · 2023-08-14T12:04:05Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+     [0.90525323, 0.42400089, 0.40641287]])
+    ```
+
+3. **明确的设备好于默认的设备**


这几个标题的说法还需要稍微润色下，感觉整体看起来风格可能像 The Zen of Python？

不会要写英文标题吧？！🤣

啊那不是，我只是觉得这几句感觉风格很像 python 之禅而已，但人家的翻译听起来会更好一些

sunzhongkai588 · 2023-08-14T19:06:04Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+> - 将 xdoctest 引入到飞桨框架工作流中, https://github.com/PaddlePaddle/community/blob/master/rfcs/Docs/%E5%B0%86%20xdoctest%20%E5%BC%95%E5%85%A5%E5%88%B0%E9%A3%9E%E6%A1%A8%E6%A1%86%E6%9E%B6%E5%B7%A5%E4%BD%9C%E6%B5%81%E4%B8%AD.md
+> - 将 xdoctest 引入到飞桨框架工作流中（补充） - 详细设计, https://github.com/PaddlePaddle/Paddle/blob/develop/tools/sampcd_processor_readme.md
+> - `doctest`, https://docs.python.org/3/library/doctest.html#module-doctest
+> - `xdoctest`, https://xdoctest.readthedocs.io/en/latest/


网址链接有点长，要不都改成引用？比如

「将 xdoctest 引入到飞桨框架工作流中」 RFC

「将 xdoctest 引入到飞桨框架工作流中」详细设计

...

sunzhongkai588 · 2023-08-14T19:41:06Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+    如：
+
+    ``` python
+    >>> # doctest: +REQUIRES(env:GPU)


似乎承袭了普通代码块的逻辑， # doctest: +REQUIRES(env:GPU) 无法显示，请修改～

这个还真有点麻烦～ sphinx 默认渲染把这个删掉的～我看看换个标注行不行～

sunzhongkai588 · 2023-08-14T19:41:58Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+    - 需要 `GPU` 环境
+
+        ``` python
+        >>> # doctest: +REQUIRES(env:GPU)
+        >>> ...
+        ```
+
+    - 需要 `XPU` 环境
+
+        ``` python
+        >>> # doctest: +REQUIRES(env:XPU)
+        >>> ...
+        ```
+
+    - 需要 `GPU`、`XPU` 等多个环境
+
+        ``` python
+        >>> # doctest: +REQUIRES(env:GPU, env:XPU)
+        >>> ...
+        ```


同样的问题， # doctest: +REQUIRES(xxx) 无法显示

sunzhongkai588 · 2023-08-14T19:43:02Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+    ``` python
+    >>> # doctest: +SKIP('file not exist')
+    >>> with open('cat.jpg') as f:
+    ...     im = load_image_bytes(f.read())
+    ```
+
+    `SKIP` 指令还可以成对使用，如：
+    ``` python
+    >>> # doctest: +SKIP('file not exist')
+    >>> with open('cat.jpg') as f:
+    ...     im = load_image_bytes(f.read())
+    >>> # doctest: -SKIP
+    >>> x = paddle.to_tensor([[1, 2], [3, 4]])
+    >>> ...
+    ```


skip也是同样的问题，没有显示

sunzhongkai588 · 2023-08-14T19:47:04Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

-如
+代码示例是 API 文档的核心部分之一，毕竟 talk is cheap，show me the code。所以，在 API 代码示例中，应该对前文描述的 API 使用中的各种场景，尽可能的在一个示例中给出，并给出对应的结果。
+
+**书写规范**


书写规范 这一节确实有些长，要不单独写一篇，然后这里通过链接的形式引过去？ @SigureMo @megemini

可以啊～

要么就像 COPY-FROM 那样单独？

可以啊～

要么就像 COPY-FROM 那样单独？

代码规范可以写在「规范和参考信息」下，新建一个文档如「文档示例代码书写规范」，描述以下示例代码的书写规范。注意新增文档时需要在 index 页面增加相关信息和引用

本文档保留相应的简要说明、注意事项和相应的例子，尽量精简～然后留一个跳转链接，如：具体细节请参考....

sunzhongkai588 · 2023-08-14T19:57:27Z

docs/dev_guides/api_contributing_guides/images/zeros_python_api.png

为啥预览里图没变..求解 @SigureMo

emmm，不太清楚，可能是有缓存？

你这儿有这情况嘛？我换了个浏览器也这样..

有呀，我是说服务器上哪里可能有缓存？本地清缓存刷新无效的

megemini · 2023-08-15T05:11:07Z

Update 20230815

由于 sphinx 对于 doctest 的渲染问题，把 python 改为 text 看看能不能正确渲染～

…pi_contributing

megemini · 2023-08-21T10:27:05Z

Update 202308021

增加 Python 文档示例代码书写规范 : docs/dev_guides/style_guide_and_references/code_example_writing_specification_cn.md

@SigureMo @sunzhongkai588 请评审～

sunzhongkai588

@SigureMo 也看看，还有文档预览里面的图片没有更新的问题

sunzhongkai588 · 2023-08-22T07:00:58Z

docs/dev_guides/style_guide_and_references/index_cn.rst

@@ -18,3 +18,4 @@
    ./error_message_writing_specification_cn.md
    ../git_guides/codestyle_check_guide_cn.md
    ../git_guides/paddle_ci_manual_cn.md
+    ./code_example_writing_specification_cn.md


不知道为什么还是有这情况... 要不试试把同目录下的，去掉 `./ `？

Suggested change

./code_example_writing_specification_cn.md

code_example_writing_specification_cn.md

SigureMo · 2023-08-22T12:10:44Z

docs/dev_guides/api_contributing_guides/api_docs_guidelines_cn.md

+                >>> import paddle
+
+                >>> x = paddle.to_tensor([[1, 2], [3, 4]])
+                >>> y = paddle.to_tensor([[5, 6], [7, 8]])
+                >>> res = paddle.multiply(x, y)
+                >>> print(res)
+                Tensor(shape=[2, 2], dtype=int64, place=Place(cpu), stop_gradient=True,
+                [[5 , 12],
+                 [21, 32]])
+
+                >>> x = paddle.to_tensor([[[1, 2, 3], [1, 2, 3]]])
+                >>> y = paddle.to_tensor([2])
+                >>> res = paddle.multiply(x, y)
+                >>> print(res)
+                Tensor(shape=[1, 2, 3], dtype=int64, place=Place(cpu), stop_gradient=True,
+                [[[2, 4, 6],
+                  [2, 4, 6]]])


这段的缩进是不是有点问题？

合的太快了 ... ... 换个 pr 修一下吧 ... ...

SigureMo

其他的看起来没啥问题～

sunzhongkai588

LGTM，之后看看预览吧

[Change] change api docs guidelines

2e37d13

paddle-bot bot added contributor status: proposed labels Aug 14, 2023

megemini mentioned this pull request Aug 14, 2023

赛题五：将 xdoctest 引入到飞桨框架工作流中 Tracking Issue PaddlePaddle/Paddle#54705

Closed

13 tasks

megemini changed the title ~~[Change] change api docs guidelines~~ 更新文档《开发 API Python 端》与《API 文档书写规范》 Aug 14, 2023

megemini changed the title ~~更新文档《开发 API Python 端》与《API 文档书写规范》~~ [Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 Aug 14, 2023

SigureMo approved these changes Aug 14, 2023

View reviewed changes

sunzhongkai588 reviewed Aug 14, 2023

View reviewed changes

luotao1 assigned luotao1, SigureMo and sunzhongkai588 Aug 15, 2023

luotao1 added the HappyOpenSource Pro 进阶版快乐开源活动，更具挑战性的任务 label Aug 15, 2023

[Change] python codeblock to text block

3312eb0

sunzhongkai588 mentioned this pull request Aug 21, 2023

[GLCC]Part-1: Add pylayer op to Support @to_static PaddlePaddle/Paddle#56108

Merged

megemini added 2 commits August 21, 2023 18:24

[Add] add code_example_writing_specification_cn.md

5140403

Merge branch 'develop' of https://github.com/PaddlePaddle/docs into a…

ffe3952

…pi_contributing

[Fix] fix code space

57f04dd

sunzhongkai588 reviewed Aug 22, 2023

View reviewed changes

[Change] remove path dot

cd68028

SigureMo reviewed Aug 22, 2023

View reviewed changes

sunzhongkai588 approved these changes Aug 23, 2023

View reviewed changes

sunzhongkai588 merged commit 434f51f into PaddlePaddle:develop Aug 23, 2023
1 check passed

megemini mentioned this pull request Dec 9, 2023

WAVE SUMMIT+2023下半年飞桨开源之星评选-信息征集 PaddlePaddle/community#765

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 #6096

[Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 #6096

megemini commented Aug 14, 2023

paddle-bot bot commented Aug 14, 2023

SigureMo left a comment

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

SigureMo Aug 14, 2023

megemini Aug 15, 2023

SigureMo Aug 15, 2023

sunzhongkai588 Aug 14, 2023

sunzhongkai588 Aug 14, 2023

megemini Aug 15, 2023

sunzhongkai588 Aug 14, 2023

sunzhongkai588 Aug 14, 2023

sunzhongkai588 Aug 14, 2023

megemini Aug 15, 2023

sunzhongkai588 Aug 21, 2023

sunzhongkai588 Aug 14, 2023

SigureMo Aug 15, 2023

sunzhongkai588 Aug 15, 2023

SigureMo Aug 15, 2023 •

edited

Loading

megemini commented Aug 15, 2023

megemini commented Aug 21, 2023

sunzhongkai588 left a comment

sunzhongkai588 Aug 22, 2023

SigureMo Aug 22, 2023

megemini Aug 23, 2023

SigureMo left a comment

sunzhongkai588 left a comment


		因此，请在书写示例代码时遵循以下规范：

		1. 显性的输出好于注释

	1. 显性的输出好于注释
	1. 显式的输出好于注释


		1. 显性的输出好于注释

		请使用 `print` 输出变量的结果。


		等，都是不建议的输出方式。

		另外，在书写/拷贝示例代码时，请注意以下几点：


		4. 能够检查好于跳过检查

		示例代码的检查可以保证其正确性，但并不是所有代码均能够正常/正确的在 CI 环境中运行。

	./code_example_writing_specification_cn.md
	code_example_writing_specification_cn.md

[Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 #6096

[Change] 更新文档《开发 API Python 端》与《API 文档书写规范》 #6096

Conversation

megemini commented Aug 14, 2023

PR types

PR changes

Description

paddle-bot bot commented Aug 14, 2023

SigureMo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SigureMo Aug 15, 2023 • edited Loading

Choose a reason for hiding this comment

megemini commented Aug 15, 2023

Update 20230815

megemini commented Aug 21, 2023

Update 202308021

sunzhongkai588 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SigureMo left a comment

Choose a reason for hiding this comment

sunzhongkai588 left a comment

Choose a reason for hiding this comment

SigureMo Aug 15, 2023 •

edited

Loading