!29339 modify apiformat

Merge pull request !29339 from xumengjuan1/code_docs_xmjformat4
2022-01-20 11:40:30 +00:00 · 2022-01-20 11:40:30 +00:00 · 1518ffbb9f
parent 764c70671f aefdba11d3
commit 1518ffbb9f
28 changed files with 60 additions and 165 deletions
--- a/docs/api/api_python/dataset/mindspore.dataset.CLUEDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.CLUEDataset.rst
@ -1,7 +1,7 @@
 mindspore.dataset.CLUEDataset
 =============================

-.. py:class:: mindspore.dataset.CLUEDataset(dataset_files, task='AFQMC', usage='train', num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
+.. py:class:: mindspore.dataset.CLUEDataset(dataset_files, task='AFQMC', usage='train', num_samples=None, num_parallel_workers=None, shuffle=Shuffle.GLOBAL, num_shards=None, shard_id=None, cache=None)

    读取和解析CLUE数据集的源文件构建数据集。

--- a/docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst
@ -1,7 +1,7 @@
 mindspore.dataset.CSVDataset
 =============================

-.. py:class:: mindspore.dataset.CSVDataset(dataset_files, field_delim=',', column_defaults=None, column_names=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
+.. py:class:: mindspore.dataset.CSVDataset(dataset_files, field_delim=',', column_defaults=None, column_names=None, num_samples=None, num_parallel_workers=None, shuffle=Shuffle.GLOBAL, num_shards=None, shard_id=None, cache=None)

    读取和解析CSV数据文件构建数据集。生成的数据集的列名和列类型取决于输入的CSV文件。

--- a/docs/api/api_python/dataset/mindspore.dataset.Dataset.d.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.Dataset.d.rst
@ -6,13 +6,13 @@

        对传入的多个数据集对象进行拼接操作，也可以使用"+"运算符来进行数据集进行拼接。

-        .. note::用于拼接的多个数据集对象，每个数据集对象的列名、每列数据的维度（rank）和数据类型必须相同。
+        .. note::
+            用于拼接的多个数据集对象，每个数据集对象的列名、每列数据的维度（rank）和数据类型必须相同。

        **参数：**

        - **datasets** (Union[list, Dataset]) - 与当前数据集对象拼接的数据集对象列表或单个数据集对象。

-
        **返回：**

        Dataset，拼接后的数据集对象。
--- a/docs/api/api_python/dataset/mindspore.dataset.Dataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.Dataset.rst
@ -4,7 +4,7 @@

        **参数：**

-        `apply_func` (function)：数据集处理函数，要求该函数的输入是一个 `Dataset` 对象，返回的是处理后的 `Dataset` 对象。
+        **apply_func** (function)：数据集处理函数，要求该函数的输入是一个 `Dataset` 对象，返回的是处理后的 `Dataset` 对象。

        **返回：**

--- a/docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst
@ -9,9 +9,9 @@

    - **source** (Union[Callable, Iterable, Random Accessible]) - 一个Python的可调用对象，可以是可迭代的Python对象，或支持随机访问的Python对象。
      
-      - 如果`source`是可调用对象，要求`source`对象可以通过 `source().next()` 的方式返回一个由NumPy数组构成的元组。
-      - 如果`source`是可迭代对象，要求`source`对象通过 `iter(source).next()` 的方式返回一个由NumPy数组构成的元组。
-      - 如果`source`是支持随机访问的对象，要求`source`对象通过 `source[idx]` 的方式返回一个由NumPy数组构成的元组。
+      - 如果 `source` 是可调用对象，要求 `source` 对象可以通过 `source().next()` 的方式返回一个由NumPy数组构成的元组。
+      - 如果 `source` 是可迭代对象，要求 `source` 对象通过 `iter(source).next()` 的方式返回一个由NumPy数组构成的元组。
+      - 如果 `source` 是支持随机访问的对象，要求 `source` 对象通过 `source[idx]` 的方式返回一个由NumPy数组构成的元组。
    - **column_names** (Union[str, list[str]]，可选) - 指定数据集生成的列名，默认值：None，不指定。用户可以通过此参数或 `schema` 参数指定列名。
    - **column_types** (list[mindspore.dtype]，可选) - 指定生成数据集各个数据列的数据类型，默认值：None，不指定。
      如果未指定该参数，则自动推断类型；如果指定了该参数，将在数据输出时做类型匹配检查。
--- a/docs/api/api_python/dataset/mindspore.dataset.GraphData.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.GraphData.rst
@ -37,7 +37,7 @@ mindspore.dataset.GraphData

        **TypeError**：参数 `edge_type` 的类型不为整型。

-    .. py:method:: get_all_neighbors(node_list, neighbor_type, output_format=<OutputFormat.NORMAL)
+    .. py:method:: get_all_neighbors(node_list, neighbor_type, output_format=OutputFormat.NORMAL)

        获取 `node_list` 所有节点的相邻节点，以 `neighbor_type` 类型返回。格式的定义参见以下示例：1表示两个节点之间连接，0表示不连接。

@ -245,7 +245,7 @@ mindspore.dataset.GraphData
        - **TypeError** - 参数 `node_list` 的类型不为列表或numpy.ndarray。
        - **TypeError** - 参数 `feature_types` 的类型不为列表或numpy.ndarray。

-    .. py:method:: get_sampled_neighbors(node_list, neighbor_nums, neighbor_types, strategy=<SamplingStrategy.RANDOM: 0>)
+    .. py:method:: get_sampled_neighbors(node_list, neighbor_nums, neighbor_types, strategy=SamplingStrategy.RANDOM)

        获取已采样相邻节点信息。此API支持多跳相邻节点采样。即将上一次采样结果作为下一跳采样的输入，最多允许6跳。采样结果平铺成列表，格式为[input node, 1-hop sampling result, 2-hop samling result ...]

@ -256,8 +256,8 @@ mindspore.dataset.GraphData
        - **neighbor_types** (Union[list, numpy.ndarray]) - 每跳采样的相邻节点类型。
        - **strategy** (SamplingStrategy, 可选) - 采样策略，默认值：mindspore.dataset.SamplingStrategy.RANDOM。取值范围：[SamplingStrategy.RANDOM, SamplingStrategy.EDGE_WEIGHT]。

-        - **SamplingStrategy.RANDOM**：随机抽样，带放回采样。
-        - **SamplingStrategy.EDGE_WEIGHT**：以边缘权重为概率进行采样。
+          - **SamplingStrategy.RANDOM**：随机抽样，带放回采样。
+          - **SamplingStrategy.EDGE_WEIGHT**：以边缘权重为概率进行采样。

        **返回：**

--- a/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst
@ -19,7 +19,7 @@ mindspore.dataset.ImageFolderDataset
    - **decode** (bool, 可选) - 是否对读取的图片进行解码操作，默认值：False，不解码。
    - **num_shards** (int, 可选) - 指定分布式训练时将数据集进行划分的分片数，默认值：None。指定此参数后， `num_samples` 表示每个分片的最大样本数。
    - **shard_id** (int, 可选) - 指定分布式训练时使用的分片ID号，默认值：None。只有当指定了 `num_shards` 时才能指定此参数。
-    - **cache** (DatasetCache, 可选) - 单节点数据缓存服务，用于加快数据集处理，详情请阅读`单节点数据缓存 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/cache.html>`_ 。默认值：None，不使用缓存。
+    - **cache** (DatasetCache, 可选) - 单节点数据缓存服务，用于加快数据集处理，详情请阅读 `单节点数据缓存 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/cache.html>`_ 。默认值：None，不使用缓存。

    **异常：**

--- a/docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst
@ -11,7 +11,7 @@
    - **columns_list** (list[str]，可选) - 指定从MindRecord文件中读取的数据列。默认值：None，读取所有列。
    - **num_parallel_workers** (int, 可选) - 指定读取数据的工作线程数。默认值：None，使用mindspore.dataset.config中配置的线程数。
    - **shuffle** (Union[bool, Shuffle], 可选) - 每个epoch中数据混洗的模式，支持传入bool类型与枚举类型进行指定，默认值：mindspore.dataset.Shuffle.GLOBAL。
-      如果`shuffle`为False，则不混洗，如果`shuffle`为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。
+      如果 `shuffle` 为False，则不混洗，如果 `shuffle` 为True，等同于将 `shuffle` 设置为mindspore.dataset.Shuffle.GLOBAL。
      通过传入枚举变量设置数据混洗的模式：

      - **Shuffle.GLOBAL**：混洗文件和文件中的数据。
@ -24,7 +24,7 @@
    - **padded_sample** (dict, 可选): 指定额外添加到数据集的样本，可用于在分布式训练时补齐分片数据，注意字典的键名需要与 `column_list` 指定的列名相同。默认值：None，不添加样本。需要与 `num_padded` 参数同时使用。
    - **num_padded** (int, 可选) - 指定额外添加的数据集样本的数量。在分布式训练时可用于为数据集补齐样本，使得总样本数量可被 `num_shards` 整除。默认值：None，不添加样本。需要与 `padded_sample` 参数同时使用。
    - **num_samples** (int, 可选) - 指定从数据集中读取的样本数。默认值：None，读取所有样本。
-    - **cache** (DatasetCache, 可选) - 单节点数据缓存服务，用于加快数据集处理，详情请阅读`单节点数据缓存 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/cache.html>`_ 。默认值：None，不使用缓存。
+    - **cache** (DatasetCache, 可选) - 单节点数据缓存服务，用于加快数据集处理，详情请阅读 `单节点数据缓存 <https://www.mindspore.cn/docs/programming_guide/zh-CN/master/cache.html>`_ 。默认值：None，不使用缓存。

    **异常：**

--- a/docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst
@ -1,7 +1,7 @@
 mindspore.dataset.TFRecordDataset
 =================================

-.. py:class:: mindspore.dataset.TFRecordDataset(dataset_files, schema=None, columns_list=None, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, shard_equal_rows=False, cache=None)
+.. py:class:: mindspore.dataset.TFRecordDataset(dataset_files, schema=None, columns_list=None, num_samples=None, num_parallel_workers=None, shuffle=Shuffle.GLOBAL, num_shards=None, shard_id=None, shard_equal_rows=False, cache=None)

    读取和解析TFData格式的数据文件构建数据集。生成的数据集的列名和列类型取决于TFRecord文件中的保存的列名与类型。

--- a/docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst
+++ b/docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst
@ -1,7 +1,7 @@
 mindspore.dataset.TextFileDataset
 ==================================

-.. py:class:: mindspore.dataset.TextFileDataset(dataset_files, num_samples=None, num_parallel_workers=None, shuffle=<Shuffle.GLOBAL: 'global'>, num_shards=None, shard_id=None, cache=None)
+.. py:class:: mindspore.dataset.TextFileDataset(dataset_files, num_samples=None, num_parallel_workers=None, shuffle=Shuffle.GLOBAL, num_shards=None, shard_id=None, cache=None)

    读取和解析文本文件构建数据集。生成的数据集有一个数据列: `[text]` ，类型为string。

--- a/docs/api/api_python/dataset_audio/mindspore.dataset.audio.transforms.AmplitudeToDB.rst
+++ b/docs/api/api_python/dataset_audio/mindspore.dataset.audio.transforms.AmplitudeToDB.rst
@ -1,7 +1,7 @@
 mindspore.dataset.audio.transforms.AmplitudeToDB
 =================================================

-.. py:class:: mindspore.dataset.audio.transforms.AmplitudeToDB(stype=<ScaleType.POWER: 'power'>, ref_value=1.0, amin=1e-10, top_db=80.0)
+.. py:class:: mindspore.dataset.audio.transforms.AmplitudeToDB(stype=ScaleType.POWER, ref_value=1.0, amin=1e-10, top_db=80.0)

    将输入音频从振幅/功率标度转换为分贝标度。

--- a/docs/api/api_python/dataset_audio/mindspore.dataset.audio.transforms.FrequencyMasking.rst
+++ b/docs/api/api_python/dataset_audio/mindspore.dataset.audio.transforms.FrequencyMasking.rst
@ -10,7 +10,7 @@ mindspore.dataset.audio.transforms.FrequencyMasking
    **参数：**

    - **iid_masks** (bool, 可选) - 是否施加随机掩码，默认值：False。
-    - **freq_mask_param** (int, 可选) - 当 `iid_masks` 为True时，掩码长度将从[0, freq_mask_param]中均匀采样；当 `iid_masks` 为False时，直接使用该值作为掩码长度。取值范围为[0, freq_length]，其中 `freq_length` 为音频波形在频域的长度，默认值：0。
+    - **frequency_mask_param** (int, 可选) - 当 `iid_masks` 为True时，掩码长度将从[0, freq_mask_param]中均匀采样；当 `iid_masks` 为False时，直接使用该值作为掩码长度。取值范围为[0, freq_length]，其中 `freq_length` 为音频波形在频域的长度，默认值：0。
    - **mask_start** (int, 可选) - 添加掩码的起始位置，只有当 `iid_masks` 为True时，该值才会生效。取值范围为[0, freq_length - freq_mask_param]，其中 `freq_length` 为音频波形在频域的长度，默认值：0。
    - **mask_value** (float, 可选) - 掩码填充值，默认值：0.0。

--- a/docs/api/api_python/mindspore/mindspore.DynamicLossScaleManager.rst
+++ b/docs/api/api_python/mindspore/mindspore.DynamicLossScaleManager.rst
@ -1,7 +1,7 @@
 mindspore.DynamicLossScaleManager
 ==================================

-.. py:class:: mindspore.DynamicLossScaleManager(init_loss_scale=2**24, scale_factor=2, scale_window=2000)
+.. py:class:: mindspore.DynamicLossScaleManager(init_loss_scale=2 ** 24, scale_factor=2, scale_window=2000)

    动态调整损失缩放系数的管理器，继承自 :class:`mindspore.LossScaleManager` 。

@ -11,15 +11,6 @@ mindspore.DynamicLossScaleManager
    - **scale_factor** (int) - 放大/缩小倍数。默认值：2。
    - **scale_window** (int) - 无溢出时的连续正常step的最大数量。默认值：2000。

-    **ÑùÀý£º**
-
-    >>> from mindspore import Model, nn, DynamicLossScaleManager
-    >>>
-    >>> net = Net()
-    >>> loss_scale_manager = DynamicLossScaleManager()
-    >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
-    >>> model = Model(net, loss_scale_manager=loss_scale_manager, optimizer=optim)
-
    .. py:method:: get_drop_overflow_update()

        该值表示是否在发生溢出时放弃本轮参数更新。
--- a/docs/api/api_python/mindspore/mindspore.Model.rst
+++ b/docs/api/api_python/mindspore/mindspore.Model.rst
@ -32,39 +32,6 @@

      如果你想设置boost模式, 可以将 `boost_config_dict` 设置为 `boost.py` 。

-    **样例:**
-
-    >>> from mindspore import Model, nn
-    >>>
-    >>> class Net(nn.Cell):
-    ...     def __init__(self, num_class=10, num_channel=1):
-    ...         super(Net, self).__init__()
-    ...         self.conv1 = nn.Conv2d(num_channel, 6, 5, pad_mode='valid')
-    ...         self.conv2 = nn.Conv2d(6, 16, 5, pad_mode='valid')
-    ...         self.fc1 = nn.Dense(16*5*5, 120, weight_init='ones')
-    ...         self.fc2 = nn.Dense(120, 84, weight_init='ones')
-    ...         self.fc3 = nn.Dense(84, num_class, weight_init='ones')
-    ...         self.relu = nn.ReLU()
-    ...         self.max_pool2d = nn.MaxPool2d(kernel_size=2, stride=2)
-    ...         self.flatten = nn.Flatten()
-    ...
-    ...     def construct(self, x):
-    ...         x = self.max_pool2d(self.relu(self.conv1(x)))
-    ...         x = self.max_pool2d(self.relu(self.conv2(x)))
-    ...         x = self.flatten(x)
-    ...         x = self.relu(self.fc1(x))
-    ...         x = self.relu(self.fc2(x))
-    ...         x = self.fc3(x)
-    ...         return x
-    >>>
-    >>> net = Net()
-    >>> loss = nn.SoftmaxCrossEntropyWithLogits()
-    >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
-    >>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None)
-    >>> # 如何构建数据集，请参考官方网站的数据集相关章节
-    >>> dataset = create_custom_dataset()
-    >>> model.train(2, dataset)
-
    .. py:method:: build(train_dataset=None, valid_dataset=None, sink_size=-1, epoch=1, jit_config=None)

        数据下沉模式下构建计算图和数据图。
@ -160,15 +127,6 @@

        返回预测结果，类型是Tensor或Tensor元组。

-        **样例:**
-
-        >>> import mindspore as ms
-        >>> from mindspore import Model, Tensor
-        >>>
-        >>> input_data = Tensor(np.random.randint(0, 255, [1, 1, 32, 32]), ms.float32)
-        >>> model = Model(Net())
-        >>> result = model.predict(input_data)
-
    .. py:method:: predict_network
        :property:

@ -195,19 +153,6 @@
        - **dataset_sink_mode** (bool) – 数据是否直接下沉至处理器进行处理。使用PYNATIVE_MODE模式或CPU处理器时，模型训练流程将以非下沉模式执行。默认值：True。
        - **sink_size** (int) – 控制每次数据下沉的数据量。`dataset_sink_mode` 为False时 `sink_size` 无效。如果sink_size=-1，则每一次epoch下沉完整数据集。如果sink_size>0，则每一次epoch下沉数据量为sink_size的数据集。默认值：-1。

-        **样例:**
-
-        >>> from mindspore import Model, nn, FixedLossScaleManager
-        >>>
-        >>> # 如何构建数据集，请参考官方网站的数据集相关章节
-        >>> dataset = create_custom_dataset()
-        >>> net = Net()
-        >>> loss = nn.SoftmaxCrossEntropyWithLogits()
-        >>> loss_scale_manager = FixedLossScaleManager()
-        >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
-        >>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None, loss_scale_manager=loss_scale_manager)
-        >>> model.train(2, dataset)
-
    .. py:method:: train_network
        :property:

--- a/docs/api/api_python/mindspore/mindspore.ParameterTuple.rst
+++ b/docs/api/api_python/mindspore/mindspore.ParameterTuple.rst
@ -16,10 +16,10 @@ mindspore.ParameterTuple

        - **prefix** (str) - Parameter的namespace，此前缀将会被添加到Parametertuple中的Parameter的name属性中。
        - **init** (Union[Tensor, str, numbers.Number]) - 对Parametertuple中Parameter的shape和类型进行克隆，并根据传入的 `init` 设置数值。默认值：'same'。
-                如果 `init` 是 `Tensor` ，则新参数的数值与该Tensor相同；
-                如果 `init` 是 `numbers.Number` ，则设置新参数的数值为该值；
-                如果 `init` 是 `str` ，则按照 `Initializer` 模块中对应的同名的初始化方法进行数值设定；
-                如果 `init` 是'same'，则新参数的数值与原Parameter相同。
+          如果 `init` 是 `Tensor` ，则新参数的数值与该Tensor相同；
+          如果 `init` 是 `numbers.Number` ，则设置新参数的数值为该值；
+          如果 `init` 是 `str` ，则按照 `Initializer` 模块中对应的同名的初始化方法进行数值设定；
+          如果 `init` 是'same'，则新参数的数值与原Parameter相同。

        **返回：**

--- a/docs/api/api_python/mindspore/mindspore.Tensor.rst
+++ b/docs/api/api_python/mindspore/mindspore.Tensor.rst
@ -224,15 +224,6 @@ mindspore.Tensor

        维度与输入张量的相同的Tensor。输出张量的维度必须遵守广播规则。广播规则指输出张量的维度需要扩展为输入张量的维度，如果目标张量的维度大于输入张量的维度，则不满足广播规则。

-        >>> import numpy as np
-        >>> from mindspore import Tensor
-        >>> from mindspore import dtype as mstype
-        >>> x = Tensor([[1, 2, 3], [1, 2, 3]], dtype=mstype.float32)
-        >>> y = Tensor(np.ones((1, 3)), dtype=mstype.float32)
-        >>> output = x.expand_as(y)
-        >>> print(output)
-        Not support shapes for broadcast, x_shape: (2, 3), target shape: (1, 3)
-
    .. py:method:: fill(value)

        用标量值填充数组。
--- a/docs/api/api_python/nn/mindspore.nn.Adagrad.rst
+++ b/docs/api/api_python/nn/mindspore.nn.Adagrad.rst
@ -39,13 +39,13 @@ mindspore.nn.Adagrad

    - **update_slots** (bool) - 如果为True，则更新累加器 :math:`h` 。默认值：True。

-    .. include:: mindspore.nn.optim_arg_loss_scale.rst
+      .. include:: mindspore.nn.optim_arg_loss_scale.rst

    - **weight_decay** (Union[float, int]) - 要乘以权重的权重衰减值，必须大于等于0.0。默认值：0.0。

    **输入：**

-    - **grads** (tuple[Tensor]) - 优化器中 `params` 的梯度，形状（shape）与 `params` 相同。
+    **grads** (tuple[Tensor]) - 优化器中 `params` 的梯度，形状（shape）与 `params` 相同。

    **输出：**

--- a/docs/api/api_python/nn/mindspore.nn.Adam.rst
+++ b/docs/api/api_python/nn/mindspore.nn.Adam.rst
@ -45,7 +45,7 @@ mindspore.nn.Adam
    - **use_nesterov** (bool) - 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
    - **weight_decay** (float) - 权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。

-    .. include:: mindspore.nn.optim_arg_loss_scale.rst
+      .. include:: mindspore.nn.optim_arg_loss_scale.rst

    **输入：**

--- a/docs/api/api_python/nn/mindspore.nn.AdamOffload.rst
+++ b/docs/api/api_python/nn/mindspore.nn.AdamOffload.rst
@ -48,7 +48,7 @@ mindspore.nn.AdamOffload
    - **use_nesterov** (bool) - 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。如果为True，使用NAG更新梯度。如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
    - **weight_decay** (float) - 权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。

-    .. include:: mindspore.nn.optim_arg_loss_scale.rst
+      .. include:: mindspore.nn.optim_arg_loss_scale.rst

    **输入：**

--- a/docs/api/api_python/nn/mindspore.nn.AdamWeightDecay.rst
+++ b/docs/api/api_python/nn/mindspore.nn.AdamWeightDecay.rst
@ -54,7 +54,7 @@ mindspore.nn.AdamWeightDecay

    **输出：**

-    **tuple** [bool]，所有元素都为True。
+    tuple[bool]，所有元素都为True。

    **异常：**

--- a/docs/api/api_python/nn/mindspore.nn.Cell.rst
+++ b/docs/api/api_python/nn/mindspore.nn.Cell.rst
@ -12,18 +12,6 @@
    - **auto_prefix** (bool) – 是否自动为Cell及其子Cell生成NameSpace。`auto_prefix` 的设置影响网络参数的命名，如果设置为True，则自动给网络参数的名称添加前缀，否则不添加前缀。默认值：True。
    - **flags** (dict) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。

-    **样例** :
-
-    >>> import mindspore.nn as nn
-    >>> import mindspore.ops as ops
-    >>> class MyCell(nn.Cell):
-    ...    def __init__(self):
-    ...        super(MyCell, self).__init__()
-    ...        self.relu = ops.ReLU()
-    ...
-    ...    def construct(self, x):
-    ...        return self.relu(x)
-
    .. py:method:: add_flags(**flags)

        为Cell添加自定义属性。
@ -96,7 +84,7 @@

        **参数：**

-        - **cell** (str) – 需要进行迭代的Cell。默认值：None。
+        - **cells** (str) – 需要进行迭代的Cell。默认值：None。
        - **name_prefix** (str) – 作用域。默认值：''。

        **返回：**
@ -210,7 +198,7 @@
        - **KeyError** – 如果子Cell的名称不正确或与其他子Cell名称重复。
        - **TypeError** – 如果子Cell的类型不正确。

-    .. py:method:: insert_param_to_cell(param_name, param, check_name=True)
+    .. py:method:: insert_param_to_cell(param_name, param, check_name_contain_dot=True)

        向当前Cell添加参数。

@ -220,7 +208,7 @@

        - **param_name** (str) – 参数名称。
        - **param** (Parameter) – 要插入到Cell的参数。
-        - **check_name** (bool) – 是否对 `param_name` 中的"."进行检查。默认值：True。
+        - **check_name_contain_dot** (bool) – 是否对 `param_name` 中的"."进行检查。默认值：True。

        **异常：**

@ -235,8 +223,7 @@

        **参数：**

-        - **params** (dict) – 用于初始化数据图的参数字典。
-
+        **params** (dict) – 用于初始化数据图的参数字典。

    .. py:method:: name_cells()

@ -308,7 +295,7 @@
            - 当应用了重计算且内存充足时，可以配置'mp_comm_recompute=False'来提升性能。
            - 当应用了重计算但内存不足时，可以配置'parallel_optimizer_comm_recompute=True'来节省内存。有相同融合group的Cell应该配置相同的parallel_optimizer_comm_recompute。

-        **参数**：
+        **参数：**

        - **mp_comm_recompute** (bool) – 表示在自动并行或半自动并行模式下，指定Cell内部由模型并行引入的通信操作是否重计算。默认值：True。
        - **parallel_optimizer_comm_recompute** (bool) – 表示在自动并行或半自动并行模式下，指定Cell内部由优化器并行引入的AllGather通信是否重计算。默认值：False。
@ -370,15 +357,15 @@

        通过并行策略对输入张量进行切分。

-        **参数**：
+        **参数：**

-        - **inputs** (tuple) – construct方法的输入。
+        **inputs** (tuple) – construct方法的输入。

    .. py:method:: set_param_fl(push_to_server=False, pull_from_server=False, requires_aggr=True)

        设置参数与服务器交互的方式。

-        **参数**：
+        **参数：**

        - **push_to_server** (bool) – 是否将参数推送到服务器。默认值：False。
        - **pull_from_server** (bool) – 是否从服务器提取参数。默认值：False。
@ -390,7 +377,7 @@

        .. note:: 只在运行的任务处于参数服务器模式时有效。

-        **参数**：
+        **参数：**

         - **recurse** (bool) – 是否设置子网络的可训练参数。默认值：True。
         - **init_in_server** (bool) – 是否在服务器上初始化由参数服务器更新的可训练参数。默认值：False。
--- a/docs/api/api_python/nn/mindspore.nn.Conv3d.rst
+++ b/docs/api/api_python/nn/mindspore.nn.Conv3d.rst
@ -12,7 +12,7 @@ mindspore.nn.Conv3d
        \sum_{k = 0}^{C_{in} - 1} \text{ccor}({\text{weight}(C_{\text{out}_j}, k), \text{X}(N_i, k)})

    其中，:math:`ccor` 为 `cross-correlation <https://en.wikipedia.org/wiki/Cross-correlation>`_ ， :math:`C_{in}` 为输入空间维度， :math:`out_{j}` 对应输出的第 :math:`j` 个空间维度，:math:`j` 的范围在 :math:`[0，C_{out}-1]` 内，
-    :math:`\text{weight}(C_{\text{out}_j}, k)`是shape为 :math:`(\text{kernel_size[0]}, \text{kernel_size[1]}, \text{kernel_size[2]})` 的卷积核切片，其中 :math:`\text{kernel_size[0]}` , :math:`\text{kernel_size[1]}和 :math:`\text{kernel_size[2]}` 是卷积核的深度、高度和宽度。 :math:`\text{bias}` 为偏置参数， :math:`\text{X}` 为输入Tensor。
+    :math:`\text{weight}(C_{\text{out}_j}, k)` 是shape为 :math:`(\text{kernel_size[0]}, \text{kernel_size[1]}, \text{kernel_size[2]})` 的卷积核切片，其中 :math:`\text{kernel_size[0]}` , :math:`\text{kernel_size[1]}和 :math:`\text{kernel_size[2]}` 是卷积核的深度、高度和宽度。 :math:`\text{bias}` 为偏置参数， :math:`\text{X}` 为输入Tensor。
    完整卷积核的shape为 :math:`(C_{out}, C_{in} / \text{group}, \text{kernel_size[0]}, \text{kernel_size[1]}, \text{kernel_size[2]})` ，其中 `group` 是在空间维度上分割输入 `x` 的组数。
    详细介绍请参考论文 `Gradient Based Learning Applied to Document Recognition <http://vision.stanford.edu/cs598_spring07/papers/Lecun98.pdf>`_ 。

@ -29,7 +29,7 @@ mindspore.nn.Conv3d
      - pad：对输入进行填充。 在输入的深度、高度和宽度方向上填充 `padding` 大小的0。如果设置此模式， `padding` 必须大于或等于0。

    - **padding** (Union(int, tuple[int])) - 输入的深度、高度和宽度方向上填充的数量。数据类型为int或包含6个整数的tuple。如果 `padding` 是一个整数，则前部、后部、顶部，底部，左边和右边的填充都等于 `padding` 。如果 `padding` 是6个整数的tuple，则前部、尾部、顶部、底部、左边和右边的填充分别等于填充padding[0]、padding[1]、padding[2]、padding[3]、padding[4]和padding[5]。值应该要大于等于0，默认值：0。
-    - **dilation** (Union[int, tuple[int]]) - 三维卷积核膨胀尺寸。数据类型为int或三个整数的tuple。若 :math:`k > 1` ，则kernel间隔 `k` 个元素进行采样。深度、高度和宽度方向上的 ｀k｀ ，其取值范围分别为[1, D]、[1, H]和[1, W]。默认值：1。
+    - **dilation** (Union[int, tuple[int]]) - 三维卷积核膨胀尺寸。数据类型为int或三个整数的tuple。若 :math:`k > 1` ，则kernel间隔 `k` 个元素进行采样。深度、高度和宽度方向上的 `k` ，其取值范围分别为[1, D]、[1, H]和[1, W]。默认值：1。
    - **group** (int) - 将过滤器拆分为组， `in_channels` 和 `out_channels` 必须可被 `group` 整除。默认值：1。当前仅支持1。
    - **has_bias** (bool) - Conv3d层是否添加偏置参数。默认值：False。
    - **weight_init** (Union[Tensor, str, Initializer, numbers.Number]) - 权重参数的初始化方法。它可以是Tensor，str，Initializer或numbers.Number。当使用str时，可选"TruncatedNormal"，"Normal"，"Uniform"，"HeUniform"和"XavierUniform"分布以及常量"One"和"Zero"分布的值，可接受别名"xavier_uniform"，"he_uniform"，"ones"和"zeros"。上述字符串大小写均可。更多细节请参考Initializer的值。默认值："normal"。
--- a/docs/api/api_python/nn/mindspore.nn.Jvp.rst
+++ b/docs/api/api_python/nn/mindspore.nn.Jvp.rst
@ -20,18 +20,3 @@ mindspore.nn.Jvp

    - **net_output** (Tensor or Tuple of Tensor) - 输入网络的正向计算结果。
    - **jvp** (Tensor or Tuple of Tensor) - 雅可比向量积的结果。
-
-    **支持平台：**
-
-    ``Ascend`` ``GPU`` ``CPU``
-
-    **样例：**
-
-    >>> from mindspore.nn import Jvp
-    >>> class Net(nn.Cell):
-    ...     def construct(self, x, y):
-    ...         return x**3 + y
-    >>> x = Tensor(np.array([[1, 2], [3, 4]]).astype(np.float32))
-    >>> y = Tensor(np.array([[1, 2], [3, 4]]).astype(np.float32))
-    >>> v = Tensor(np.array([[1, 1], [1, 1]]).astype(np.float32))
-    >>> output = Jvp(Net())(x, y, (v, v))
--- a/docs/api/api_python/nn/mindspore.nn.PipelineCell.rst
+++ b/docs/api/api_python/nn/mindspore.nn.PipelineCell.rst
@ -5,7 +5,7 @@
    .. note::
        micro_size必须大于或等于流水线stage的个数。

-    ** 参数：**
+    **参数：**

    - **network** (Cell) - 要修饰的目标网络。
    - **micro_size** (int) - MicroBatch大小。
--- a/docs/api/api_python/nn/mindspore.nn.SGD.rst
+++ b/docs/api/api_python/nn/mindspore.nn.SGD.rst
@ -49,7 +49,7 @@ mindspore.nn.SGD
    - **weight_decay** (float): 权重衰减（L2 penalty），必须大于等于0。默认值：0.0。
    - **nesterov** (bool): 启用Nesterov动量。如果使用Nesterov，动量必须为正，阻尼必须等于0.0。默认值：False。

-    .. include:: mindspore.nn.optim_arg_loss_scale.rst
+      .. include:: mindspore.nn.optim_arg_loss_scale.rst

    **输入：**

--- a/docs/api/api_python/nn/mindspore.nn.conv2d.rst
+++ b/docs/api/api_python/nn/mindspore.nn.conv2d.rst
@ -18,23 +18,23 @@ mindspore.nn.Conv2d

   **参数：**

-     - **in_channels** (`int`) – Conv2d层输入Tensor的空间维度。
-     - **out_channels** (`dict`) - Conv2d层输出Tensor的空间维度。
-     - **kernel_size** (`Union[int, tuple[int]]`) – 指定二维卷积核的高度和宽度。数据类型为整型或两个整型的tuple。一个整数表示卷积核的高度和宽度均为该值。两个整数的tuple分别表示卷积核的高度和宽度。
-     - **stride** (`Union[int, tuple[int]]`) – 二维卷积核的移动步长。数据类型为整型或两个整型的tuple。一个整数表示在高度和宽度方向的移动步长均为该值。两个整数的tuple分别表示在高度和宽度方向的移动步长。默认值：1。
-     - **pad_mode** (`str`) – 指定填充模式。可选值为"same"、"valid"、"pad"。默认值："same"。
+   - **in_channels** (`int`) – Conv2d层输入Tensor的空间维度。
+   - **out_channels** (`dict`) - Conv2d层输出Tensor的空间维度。
+   - **kernel_size** (`Union[int, tuple[int]]`) – 指定二维卷积核的高度和宽度。数据类型为整型或两个整型的tuple。一个整数表示卷积核的高度和宽度均为该值。两个整数的tuple分别表示卷积核的高度和宽度。
+   - **stride** (`Union[int, tuple[int]]`) – 二维卷积核的移动步长。数据类型为整型或两个整型的tuple。一个整数表示在高度和宽度方向的移动步长均为该值。两个整数的tuple分别表示在高度和宽度方向的移动步长。默认值：1。
+   - **pad_mode** (`str`) – 指定填充模式。可选值为"same"、"valid"、"pad"。默认值："same"。

-       - **same**：输出的高度和宽度分别与输入整除 `stride` 后的值相同。若设置该模式，`padding` 的值必须为0。
-       - **valid**：在不填充的前提下返回有效计算所得的输出。不满足计算的多余像素会被丢弃。如果设置此模式，则 `padding` 的值必须为0。
-       - **pad**：对输入进行填充。在输入的高度和宽度方向上填充 `padding` 大小的0。如果设置此模式， `padding` 必须大于或等于0。
+     - **same**：输出的高度和宽度分别与输入整除 `stride` 后的值相同。若设置该模式，`padding` 的值必须为0。
+     - **valid**：在不填充的前提下返回有效计算所得的输出。不满足计算的多余像素会被丢弃。如果设置此模式，则 `padding` 的值必须为0。
+     - **pad**：对输入进行填充。在输入的高度和宽度方向上填充 `padding` 大小的0。如果设置此模式， `padding` 必须大于或等于0。

-     - **padding** (`Union[int, tuple[int]]`) –  输入的高度和宽度方向上填充的数量。数据类型为int或包含4个整数的tuple。如果 `padding` 是一个整数，那么上、下、左、右的填充都等于 `padding` 。如果 `padding` 是一个有4个整数的tuple，那么上、下、左、右的填充分别等于 `padding[0]` 、 `padding[1]` 、 `padding[2]` 和 `padding[3]` 。值应该要大于等于0，默认值：0。
-     - **dilation** (`Union[int, tuple[int]]`) –  二维卷积核膨胀尺寸。数据类型为整型或具有两个整型的tuple。若 :math:`k > 1` ，则kernel间隔 `k` 个元素进行采样。垂直和水平方向上的 ｀k｀ ，其取值范围分别为[1, H]和[1, W]。默认值：1。
-     - **group** (`int`) –  将过滤器拆分为组， `in_channels` 和 `out_channels` 必须可被 `group` 整除。如果组数等于 `in_channels` 和 `out_channels` ，这个二维卷积层也被称为二维深度卷积层。默认值：1.
-     - **has_bias** (`bool`) –  Conv2d层是否添加偏置参数。默认值：False。
-     - **weight_init** (Union[Tensor, str, Initializer, numbers.Number]) - 权重参数的初始化方法。它可以是Tensor，str，Initializer或numbers.Number。当使用str时，可选"TruncatedNormal"，"Normal"，"Uniform"，"HeUniform"和"XavierUniform"分布以及常量"One"和"Zero"分布的值，可接受别名"xavier_uniform"，"he_uniform"，"ones"和"zeros"。上述字符串大小写均可。更多细节请参考Initializer的值。默认值："normal"。
-     - **bias_init** (Union[Tensor, str, Initializer, numbers.Number]) - 偏置参数的初始化方法。可以使用的初始化方法与"weight_init"相同。更多细节请参考Initializer的值。默认值："zeros"。
-     - **data_format** (`str`) –  数据格式的可选值有"NHWC"，"NCHW"。默认值："NCHW"。
+   - **padding** (`Union[int, tuple[int]]`) –  输入的高度和宽度方向上填充的数量。数据类型为int或包含4个整数的tuple。如果 `padding` 是一个整数，那么上、下、左、右的填充都等于 `padding` 。如果 `padding` 是一个有4个整数的tuple，那么上、下、左、右的填充分别等于 `padding[0]` 、 `padding[1]` 、 `padding[2]` 和 `padding[3]` 。值应该要大于等于0，默认值：0。
+   - **dilation** (`Union[int, tuple[int]]`) –  二维卷积核膨胀尺寸。数据类型为整型或具有两个整型的tuple。若 :math:`k > 1` ，则kernel间隔 `k` 个元素进行采样。垂直和水平方向上的 ｀k｀ ，其取值范围分别为[1, H]和[1, W]。默认值：1。
+   - **group** (`int`) –  将过滤器拆分为组， `in_channels` 和 `out_channels` 必须可被 `group` 整除。如果组数等于 `in_channels` 和 `out_channels` ，这个二维卷积层也被称为二维深度卷积层。默认值：1.
+   - **has_bias** (`bool`) –  Conv2d层是否添加偏置参数。默认值：False。
+   - **weight_init** (Union[Tensor, str, Initializer, numbers.Number]) - 权重参数的初始化方法。它可以是Tensor，str，Initializer或numbers.Number。当使用str时，可选"TruncatedNormal"，"Normal"，"Uniform"，"HeUniform"和"XavierUniform"分布以及常量"One"和"Zero"分布的值，可接受别名"xavier_uniform"，"he_uniform"，"ones"和"zeros"。上述字符串大小写均可。更多细节请参考Initializer的值。默认值："normal"。
+   - **bias_init** (Union[Tensor, str, Initializer, numbers.Number]) - 偏置参数的初始化方法。可以使用的初始化方法与"weight_init"相同。更多细节请参考Initializer的值。默认值："zeros"。
+   - **data_format** (`str`) –  数据格式的可选值有"NHWC"，"NCHW"。默认值："NCHW"。

   **输入：**

--- a/docs/api/api_python/nn_probability/mindspore.nn.probability.distribution.TransformedDistribution.rst
+++ b/docs/api/api_python/nn_probability/mindspore.nn.probability.distribution.TransformedDistribution.rst
@ -19,5 +19,6 @@ mindspore.nn.probability.distribution.TransformedDistribution

    **异常：**

-    - **ValueError** - bijector不是Bijector类，distribution不是Distribution类。
+    - **TypeError** - bijector不是Bijector类。
+    - **TypeError** - distribution不是Distribution类。

--- a/docs/api/api_python/ops/mindspore.ops.Log.rst
+++ b/docs/api/api_python/ops/mindspore.ops.Log.rst
@ -25,10 +25,5 @@ mindspore.ops.Log

    **异常：**

-    - **TypeError** - `x` 不是Tensor。
+    **TypeError** - `x` 不是Tensor。

-    >>> x = Tensor(np.array([1.0, 2.0, 4.0]), mindspore.float32)
-    >>> log = ops.Log()
-    >>> output = log(x)
-    >>> print(output)
-    [0.        0.6931472 1.3862944]