修改目前 Paddle docs 中仍使用 code-block 的示例代码为 COPY-FROM

[megemini]

整体进度 （20/20）

按完成时间顺序，排名不分先后： @Liyulingyue (3) @RedContritio (4.5) @enkilee (3) @Li-fAngyU (1) @Ainavo (3) @gouzil (2) @megemini (0.5) @jjyaoao (3)

序号	分组 ID	认领人 Github	修复 PR 链接
✅ 1	others	@Ainavo	#5960 , PaddlePaddle/Paddle#55411
✅2	jit	@gouzil	#5983, PaddlePaddle/Paddle#54920
✅ 3	autograd	@gouzil	#5984, PaddlePaddle/Paddle#54921
✅4	optimizer	@jjyaoao	#6005, PaddlePaddle/Paddle#55238
✅ 5	nn	@Li-fAngyU	PaddlePaddle/Paddle#54889, #5975
✅ 6	metric	@RedContritio, @megemini	PaddlePaddle/Paddle#55052, #5971
✅ 7	utils	@Liyulingyue	无需修复
✅ 8	hub	@RedContritio	无需修复
✅ 9	geometric	@Liyulingyue	无需修复
✅ 10	vision	@Liyulingyue	无需修复
✅ 11	fft	@RedContritio	无需修复
✅12	io	@RedContritio	#6001, PaddlePaddle/Paddle#55221
✅13	distributed	@jjyaoao	#6004 , PaddlePaddle/Paddle#55236
✅14	incubate	@jjyaoao	#6003 , PaddlePaddle/Paddle#55234
✅15	regularizer	@Ainavo	PaddlePaddle/Paddle#54926 , #5961
✅16	profiler	@Ainavo	无需修复
✅ 17	linalg	@RedContritio	无需修复
✅18	static	@enkilee	#5964, PaddlePaddle/Paddle#54842
✅19	distribution	@enkilee	#5965, PaddlePaddle/Paddle#54843
✅ 20	text	@enkilee	无需修复
21	fluid

Updated 20230628 by megemini

非常感谢大家能来认领任务！🥳

由于任务比较多，这里补充一下 PR 的格式等问题：

• PR 标题格式： 修改COPY-FROM No. xxx
• PR 的 Description 中请 关联此 ISSUE
• 如果任务涉及 Paddle 中 docstring 的修改，请在 docs 中的 PR 中标注 Paddle 那边的 PR，如：
  PADDLEPADDLE_PR=12345

这里引用一下 @Li-fAngyU 同学提的 PR 作为参考：

docs 的 PR

Paddle 的 PR

另外，修改 Paddle 的 docstring 时，请注意缩进，以及 :name: 的使用，如：

class SomeAPI:
    """
    This is SomeAPI doc string description ...
    非 Example(s): 下的代码段，必须加 name 标识符。

    .. code-block:: python
        :name: code-example1

        import paddle
        from paddle.nn import SomeAPI

    Examples:

        .. code-block:: python

            # 若 Example(s): 下只有一个代码段，不用加 name 标识符。
            import paddle
            from paddle.nn import SomeAPI
    """

class SomeAPI:
    """
    This is SomeAPI doc string description ...
    若 Example(s): 下有多个代码段，需要加 name 标识符以区分。

    Examples:

        .. code-block:: python
            :name: code-example1

            import paddle
            from paddle.nn import SomeAPI

        .. code-block:: python
            :name: code-example2

            import paddle
            from paddle.nn import SomeAPI
    """

• 若 Example(s): 下只有一个代码段，不用加 name 标识符。
• 若 Example(s): 下有多个代码段，需要加 name 标识符以区分。
• 非 Example(s): 下的代码段，必须加 name 标识符。

非常感谢！：）

---

大家好！

目前 docs 中的中文文档(rst 文档)代码段大多使用 COPY-FROM 直接从 API 的 docstring 中提取，但，由于历史遗留问题，部分代码仍然使用 .. code-block:: 直接书写。

为了统一 docs 中所有的代码块 .. code-block:: 使用 COPY-FROM 指令代替，特开此活动，欢迎大家参与，一同完善飞桨的文档 ～ 🎉🎉🎉

COPY-FORM 的具体用法，可以参考 中文API文档复制英文API文档示例代码

这里补充说明一下：

• 若 Example: 下只有一个代码段，不用加 name 标识符。
• 若 Example: 下有多个代码段，需要加 name 标识符以区分。
• 非 Example: 下的代码段，必须加 name 标识符。

特别说明一下 非 Example: 下的代码段 这种情况。如 paddle.scatter 这个接口，其 rst 中文文档：

.. _cn_api_paddle_cn_scatter:

scatter
-------------------------------
.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None)


通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下：

    .. code-block:: python

        import paddle
        #input:
        x = paddle.to_tensor([[1, 1], [2, 2], [3, 3]], dtype='float32')
        index = paddle.to_tensor([2, 1, 0, 1], dtype='int64')
        # shape of updates should be the same as x
        # shape of updates with dim > 1 should be the same as input
        updates = paddle.to_tensor([[1, 1], [2, 2], [3, 3], [4, 4]], dtype='float32')
        overwrite = False

        ...
...

参数
:::::::::
    ...

返回
:::::::::
...

代码示例
:::::::::


.. code-block:: python

    import paddle
    
    x = paddle.to_tensor([[1, 1], [2, 2], [3, 3]], dtype='float32')
    index = paddle.to_tensor([2, 1, 0, 1], dtype='int64')
    updates = paddle.to_tensor([[1, 1], [2, 2], [3, 3], [4, 4]], dtype='float32')

...

其文档在方法的描述部分与代码示例部分，使用了 .. code-block:: python 而不是 COPY-FROM。

因此，需要修改此 rst 文档，以及接口的 docstring，如：

.. _cn_api_paddle_cn_scatter:

scatter
-------------------------------
.. py:function:: paddle.scatter(x, index, updates, overwrite=True, name=None)

通过基于 ``updates`` 来更新选定索引 ``index`` 上的输入来获得输出。具体行为如下：

COPY-FROM: paddle.scatter:code-example1

...

参数
:::::::::
    ...

返回
:::::::::
...

代码示例
:::::::::

COPY-FROM: paddle.scatter

...

并修改 Paddle 代码相应接口的 docstring 描述部分中的 .. code-block:: 带有 :name: code-example1。

注意 此次任务中，如果 rst 文档中有使用 .. code-block:: text 的地方，暂不修改。

---

此次活动采取任务认领的方式进行，我们将目前统计的问题文档按照目录进行划分, 认领的同学在 issue 下回复认领的任务组 ID 即可，欢迎大家认领任务和提 PR ~。

注：

• 该任务时间：PR 截止合入时间是 7月9日，之后请勿提交。
• 认领规则：直接在 issue 下回复认领的任务组 ID 。
• PR 通过 CI 后，可以评论里或者 review request @sunzhongkai588 研发会进行审核
• PR 标题格式：修改COPY-FROM No. xxx （该任务 PR 较多，请大家遵守标题格式，避免遗漏审核）

还有其他问题的，可在此 issue 下回复进行提问！

欢迎大家参与！

---

问题文档 commit 1a4925e

other

• tolist_cn.rst
• transpose_cn.rst
• multiplex_cn.rst
• gather_cn.rst
• t_cn.rst
• scatter_cn.rst
• LazyGuard_cn.rst
• uniform_cn.rst
• Tensor_cn.rst
• flatten_cn.rst
• to_tensor_cn.rst
• grad_cn.rst
• round_cn.rst
• stack_cn.rst
• squeeze_cn.rst
• add_n_cn.rst

jit

• jit/ProgramTranslator_cn.rst
• jit/load_cn.rst
• jit/TranslatedLayer_cn.rst

autograd

• autograd/PyLayer_cn.rst
• autograd/PyLayerContext_cn.rst
• autograd/saved_tensors_hooks_cn.rst

optimizer

• optimizer/Momentum_cn.rst
• optimizer/RMSProp_cn.rst
• optimizer/Adam_cn.rst
• optimizer/Adadelta_cn.rst
• optimizer/SGD_cn.rst
• optimizer/Optimizer_cn.rst
• optimizer/AdamW_cn.rst
• optimizer/Adamax_cn.rst
• optimizer/Lamb_cn.rst
• optimizer/lr/MultiStepDecay_cn.rst
• optimizer/lr/LambdaDecay_cn.rst
• optimizer/lr/PiecewiseDecay_cn.rst
• optimizer/lr/StepDecay_cn.rst
• optimizer/lr/LRScheduler_cn.rst
• optimizer/lr/MultiplicativeDecay_cn.rst

nn

• nn/PixelUnshuffle_cn.rst
• nn/Softmax_cn.rst
• nn/Transformer_cn.rst
• nn/Embedding_cn.rst
• nn/PixelShuffle_cn.rst
• nn/LayerDict_cn.rst
• nn/initializer/Orthogonal_cn.rst
• nn/functional/grid_sample_cn.rst
• nn/functional/embedding_cn.rst
• nn/functional/pad_cn.rst
• nn/functional/softmax_cn.rst
• nn/functional/one_hot_cn.rst

metric

• metric/Accuracy__upper_cn.rst
• metric/Recall_cn.rst
• metric/Auc_cn.rst
• metric/Precision_cn.rst
• metric/Metric_cn.rst

utils

• utils/cpp_extension/load_cn.rst
• utils/cpp_extension/CppExtension_cn.rst
• utils/cpp_extension/CUDAExtension_cn.rst
• utils/cpp_extension/setup_cn.rst

hub

• hub/Overview_cn.rst

geometric

• geometric/send_uv_cn.rst
• geometric/send_u_recv_cn.rst
• geometric/send_ue_recv_cn.rst

vision

• vision/transforms/BaseTransform_cn.rst
• vision/datasets/ImageFolder_cn.rst
• vision/datasets/DatasetFolder_cn.rst

fft

• fft/rfftfreq_cn.rst

io

• io/DataLoader_cn.rst
• io/DistributedBatchSampler_cn.rst

distributed

• distributed/launch_cn.rst
• distributed/QueueDataset_cn.rst
• distributed/fleet/DistributedStrategy_cn.rst
• distributed/fleet/Fleet_cn.rst
• distributed/fleet/UserDefinedRoleMaker_cn.rst
• distributed/fleet/PaddleCloudRoleMaker_cn.rst
• distributed/fleet/UtilBase_cn.rst
• distributed/fleet/utils/HDFSClient_cn.rst

incubate

• incubate/graph_reindex_cn.rst
• incubate/graph_send_recv_cn.rst
• incubate/LookAhead_cn.rst
• incubate/optimizer/functional/minimize_lbfgs_cn.rst
• incubate/optimizer/functional/minimize_bfgs_cn.rst
• incubate/nn/functional/fused_feedforward_cn.rst
• incubate/nn/functional/fused_multi_head_attention_cn.rst

regularizer

• regularizer/L1Decay_cn.rst
• regularizer/L2Decay_cn.rst

profiler

• profiler/make_scheduler_cn.rst

linalg

• linalg/lu_unpack_cn.rst
• linalg/lu_cn.rst

static

• static/Program_cn.rst
• static/InputSpec_cn.rst
• static/program_guard_cn.rst
• static/Variable_cn.rst
• static/nn/fc_cn.rst
• static/nn/cond_cn.rst
• static/nn/sequence_slice_cn.rst

distribution

• distribution/Bernoulli_cn.rst
• distribution/Categorical_cn.rst

text

• text/Overview_cn.rst

---

关联链接：

• [Change]修改目前 Paddle docs 中 COPY-FROM 的逻辑
• [Add]将 xdoctest 引入到飞桨框架工作流中v1
• 赛题五：将 xdoctest 引入到飞桨框架工作流中 Tracking Issue

@SigureMo @luotao1 @jzhang533 @sunzhongkai588

[SigureMo]

辛苦了～

fluid

fluid 就不用了，fluid API 在 2.5 已经基本清除了，大多是遗留文档，如果将来有 CI 检查的话，可以把 fluid 跳过

.. code-block:: 标注为 text 而不是 python。

另外，CI 本身应该只检测 python code-block，其实 text code-block 不用 COPY-FROM 也没有关系，因为本任务的目标是「移除 docs 中的 example 检测，即让 docs 下再无 python code-block 即可」

[RedContritio]

认领 6, 17

[gouzil]

认领 2、3

[Ainavo]

认领1、15、16

[enkilee]

18 19 20

[RedContritio]

认领 8，11

[enkilee]

@Liyulingyue 7 9 10

[Liyulingyue]

#5957 (comment)
7 9 10 均无需使用copy-from

[enkilee]

18 chinese #5964
english PaddlePaddle/Paddle#54842

[enkilee]

19
chinese #5965
english PaddlePaddle/Paddle#54843

[enkilee]

20 看起来无需修改

[RedContritio]

11，17 无需修复

8 hub 的引用代码段不来自 PaddlePaddle/Paddle 仓库，这个需要处理吗？

代码示例
:::::::::


.. code-block:: python


    import paddle


    # PaddleClas
    models = paddle.hub.list('PaddlePaddle/PaddleClas:develop', source='github', force_reload=True,)
    print(models)


    docs = paddle.hub.help('PaddlePaddle/PaddleClas:develop', 'alexnet', source='github', force_reload=False,)
    print(docs)


    model = paddle.hub.load('PaddlePaddle/PaddleClas:develop', 'alexnet', source='github', force_reload=False, pretrained=True)
    data = paddle.rand((1, 3, 224, 224))
    out = model(data)
    print(out.shape) # [1, 1000]




    # PaddleNLP
    docs = paddle.hub.help('PaddlePaddle/PaddleNLP:develop', model='bert',)
    print(docs)


    model, tokenizer = paddle.hub.load('PaddlePaddle/PaddleNLP:develop', model='bert', model_name_or_path='bert-base-cased')

[RedContritio]

认领 12

[Li-fAngyU]

认领 5

[SigureMo]

8 hub 的引用代码段不来自 PaddlePaddle/Paddle 仓库，这个需要处理吗？

@megemini Overview 的按理说也不需要检查，所以我们 CI 检查无 .. code-block:: python 的文件应该限制在：

• docs/api 下
• 非 Overview
• 非 index
• 非 docs/api/paddle/fluid/*

cc @RedContritio

[Li-fAngyU]

辛苦了～

fluid

fluid 就不用了，fluid API 在 2.5 已经基本清除了，大多是遗留文档，如果将来有 CI 检查的话，可以把 fluid 跳过

.. code-block:: 标注为 text 而不是 python。

另外，CI 本身应该只检测 python code-block，其实 text code-block 不用 COPY-FROM 也没有关系，因为本任务的目标是「移除 docs 中的 example 检测，即让 docs 下再无 python code-block 即可」

@SigureMo 请问，这里的意思是 docs 里的 .. code-block:: text 无需修改成COPY-FROM吗？

比如paddle.nn.PixelUnshuffle里的示例：

.. code-block:: text

    给定一个形为 x.shape = [1, 1, 12, 12] 的 4-D Tensor
    设定 downscale_factor = 3
    那么输出 Tensor 的形为 [1, 9, 4, 4]

[SigureMo]

@SigureMo 请问，这里的意思是 docs 里的 .. code-block:: text 无需修改成COPY-FROM吗？

是的

[Ainavo]

认领1、15、16

16 无需修复

.. _cn_api_profiler_make_scheduler:

make_scheduler
---------------------

.. py:function:: paddle.profiler.make_scheduler(*, closed: int, ready: int, record: int, repeat: int=0, skip_first: int=0)

生成性能分析器状态(详情见 :ref:`状态说明 <cn_api_profiler_profilerstate>` )的调度器函数，可根据设置的参数来调度性能分析器的状态。
调度器用于调度如下状态转换过程：

.. code-block:: text

        (CLOSED)  (CLOSED)    (CLOSED)  (READY)    (RECORD,last RETURN)      (CLOSED)
        START -> skip_first -> closed -> ready    ->    record       ->      END
                                |                        |
                                |                        | (if has_repeated < repeat)
                                - - - - - - - - - - - -

        注：repeat <= 0 意味着该状态转换过程会持续到性能分析器结束。

参数
...

[luotao1]

修改目前 Paddle docs 中仍使用 code-block 的示例代码为 COPY-FROM 已全部完成，感谢参与的小伙伴们！

按完成时间顺序，排名不分先后： @Liyulingyue (3) @RedContritio (4.5) @enkilee (3) @Li-fAngyU (1) @Ainavo (3) @gouzil (2) @megemini (0.5) @jjyaoao (3)

欢迎继续参与快乐开源的其他任务！