!31927 Fix format in dump API

Merge pull request !31927 from maning202007/code_docs_dump_api

docs/api/api_python/mindspore/mindspore.set_dump.rst

@@ -3,9 +3,9 @@ mindspore.set_dump
 
 .. py:class:: mindspore.set_dump(target, enabled=True)
 
-    启用或者禁用target及其子节点的Dump数据功能。
+    启用或者禁用 `target` 及其子节点的Dump数据功能。
 
-    target为 `Cell <https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Cell.html#mindspore.nn.Cell>`_ 或 `Primitive <https://www.mindspore.cn/docs/api/zh-CN/master/api_python/ops/mindspore.ops.Primitive.html#mindspore.ops.Primitive>`_ 的实例。请注意，此API仅在开启异步Dump功能且Dump配置文件中的 `dump_mode` 字段为"2"时生效。有关详细信息，请参阅 `Dump功能文档 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dump_in_graph_mode.html>`_ 。默认状态下，Cell和Primitive实例不使能Dump数据功能。
+    `target` 为 :class:`mindspore.nn.Cell` 或 :class:`mindspore.ops.Primitive` 的实例。请注意，此API仅在开启异步Dump功能且Dump配置文件中的 `dump_mode` 字段为"2"时生效。有关详细信息，请参阅 `Dump功能文档 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dump_in_graph_mode.html>`_ 。默认状态下， :class:`mindspore.nn.Cell` 和 :class:`mindspore.ops.Primitive` 实例不使能Dump数据功能。
 
     .. Warning::
         此类中的所有API均为实验版本，将来可能更改或者删除。
@@ -13,10 +13,10 @@ mindspore.set_dump
     .. Note::
         - 此API只在Ascend后端的图模式有效。
         - 此API只支持训练开始前调用。如果在训练过程中调用这个API，可能不会有效果。
-        - 使用set_dump(Cell, True)后，Cell正向计算和反向计算（梯度运算产生的计算）中的算子会被Dump。
-        - 对于 `nn.SoftMaxCrossEntropyWithLogits 层 <https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.SoftmaxCrossEntropyWithLogits.html#mindspore.nn.SoftmaxCrossEntropyWithLogits>`_ ，正向计算和反向计算使用同一组算子。因此，只能看到反向计算中的Dump数据。请注意，当使用sparse=True和reduce=“mean”初始化时，nn.SoftmaxCrossEntropyWithLogits层也将在内部使用这些算子。
+        - 使用 `set_dump(Cell, True)` 后，Cell正向计算和反向计算（梯度运算产生的计算）中的算子会被Dump。
+        - 对于 :class:`mindspore.nn.SoftMaxCrossEntropyWithLogits` 层，正向计算和反向计算使用同一组算子。因此，只能看到反向计算中的Dump数据。请注意，当使用 `sparse=True` 和 `reduce=“mean”` 初始化时， :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` 层也将在内部使用这些算子。
 
     **参数：**
 
     - **target** (Union[Cell, Primitive]) - 要设置Dump标志的Cell或Primitive的实例。
-    - **enabled** (bool) - True表示启用Dump，False表示禁用Dump，默认值: True。
+    - **enabled** (bool，可选) - True表示启用Dump，False表示禁用Dump，默认值：True。

docs/api/api_python/train/mindspore.train.callback.SummaryCollector.rst

@@ -6,6 +6,7 @@
     SummaryCollector还可以允许通过 `summary算子 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#summarysummarycollector>`_ 将数据收集到summary文件中。
 
     .. note::
+        - 使用SummaryCollector时，需要将代码放置到 `if __name__ == "__main__"` 中运行。
         - 不允许在回调列表中存在多个SummaryCollector实例。
         - 并非所有信息都可以在训练阶段或评估阶段收集。
         - SummaryCollector始终记录summary算子收集的数据。

docs/api/api_python/train/mindspore.train.callback.SummaryLandscape.rst

@@ -3,6 +3,7 @@
     SummaryLandscape可以帮助您收集loss地形图的信息。通过计算loss，可以在PCA（Principal Component Analysis）方向或者随机方向创建地形图。
 
     .. note::
+        - 使用SummaryLandscape时，需要将代码放置到 `if __name__ == "__main__"` 中运行。
         - SummaryLandscape仅支持Linux系统。
 
     **参数：**

docs/api/api_python/train/mindspore.train.summary.SummaryRecord.rst

@@ -7,6 +7,7 @@
     它通过执行 `record` 方法将数据写入文件。除了通过 `summary算子 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#summarysummarycollector>`_ 记录网络的数据外，SummaryRecord还支持通过 `自定义回调函数和自定义训练循环 <https://www.mindspore.cn/mindinsight/docs/zh-CN/master/summary_record.html#callback>`_ 记录数据。
 
     .. note::
+        - 使用SummaryRecord时，需要将代码放置到 `if __name__ == "__main__"` 中运行。
         - 确保在最后关闭SummaryRecord，否则进程不会退出。请参阅下面的示例部分，了解如何用两种方式正确关闭SummaryRecord。
         - 每次训练只允许创建一个SummaryRecord实例，否则会导致数据写入异常。
         - SummaryRecord仅支持Linux系统。

mindspore/python/mindspore/common/dump.py

@@ -21,14 +21,13 @@ from mindspore._c_expression import security
 
 def set_dump(target, enabled=True):
     """
-    Enable or disable dump for the target and its contents.
+    Enable or disable dump for the `target` and its contents.
 
-    Target should be an instance of `Cell <https://www.mindspore.cn/docs/api/en/master/api_python/nn/
-    mindspore.nn.Cell.html#mindspore.nn.Cell>`_ or `Primitive <https://www.mindspore.cn/docs/api/en/master/
-    api_python/ops/mindspore.ops.Primitive.html#mindspore.ops.Primitive>`_ . Please note that this API takes
-    effect only when Asynchronous Dump is enabled and the dump_mode field in dump config file is 2. See the
-    `dump document <https://mindspore.cn/docs/programming_guide/en/master/dump_in_graph_mode.html>`_
-    for details. The default enabled status for a cell or primitive is False.
+    `target` should be an instance of :class:`mindspore.nn.Cell` or :class:`mindspore.ops.Primitive` .
+    Please note that this API takes effect only when Asynchronous Dump is enabled and the `dump_mode`
+    field in dump config file is "2". See the `dump document <https://mindspore.cn/docs/programming_guide/
+    en/master/dump_in_graph_mode.html>`_ for details.
+    The default enabled status for a :class:`mindspore.nn.Cell` or :class:`mindspore.ops.Primitive` is False.
 
     .. warning::
         This is an experimental prototype that is subject to change or deletion.
@@ -37,23 +36,20 @@ def set_dump(target, enabled=True):
         1. This API is only effective for GRAPH_MODE with Ascend backend.
         2. This API only supports being called before training starts.
            If you call this API during training, it may not be effective.
-        3. After using set_dump(cell, True), operators in forward and backward
+        3. After using `set_dump(Cell, True)` , operators in forward and backward
            computation  (computation generated by the grad operations) of the
            cell will be dumped.
-        4. For `nn.SparseSoftmaxCrossEntropyWithLogits
-           <https://www.mindspore.cn/docs/api/en/master/api_python/nn/
-           mindspore.nn.SoftmaxCrossEntropyWithLogits.html#mindspore.nn
-           .SoftmaxCrossEntropyWithLogits>`_ layer, the forward
+        4. For :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` layer, the forward
            computation and backward computation use the same set of
            operators. So you can only see dump data from backward computation.
-           Please note that nn.SoftmaxCrossEntropyWithLogits layer will also use
-           the above operators internally when initialized with sparse=True and
-           reduction="mean".
+           Please note that :class:`mindspore.nn.SoftmaxCrossEntropyWithLogits` layer will also use
+           the above operators internally when initialized with `sparse=True` and
+           `reduction="mean"` .
 
     Args:
         target (Union[Cell, Primitive]): The Cell instance or Primitive instance
             to which the dump flag is set.
-        enabled (bool): True means enable dump, False means disable dump.
+        enabled (bool, optional): True means enable dump, False means disable dump.
             Default: True.
 
     Supported Platforms:

mindspore/python/mindspore/train/callback/_landscape.py

@@ -169,7 +169,8 @@ class SummaryLandscape:
     It can create landscape in PCA direction or random direction by calculating loss.
 
     Note:
-        1. SummaryLandscape only supports Linux systems.
+        1. When using SummaryLandscape, you need to run the code in `if __name__ == "__main__"` .
+        2. SummaryLandscape only supports Linux systems.
 
     Args:
         summary_dir (str): The path of summary is used to save the model weight,

mindspore/python/mindspore/train/callback/_summary_collector.py

@@ -75,11 +75,12 @@ class SummaryCollector(Callback):
     SummaryCollector also enables the summary operator to collect data to summary files.
 
     Note:
-        1. Multiple SummaryCollector instances in callback list are not allowed.
-        2. Not all information is collected at the training phase or at the eval phase.
-        3. SummaryCollector always record the data collected by the summary operator.
-        4. SummaryCollector only supports Linux systems.
-        5. The Summary is not supported when compile source with `-s on` option.
+        1. When using SummaryCollector, you need to run the code in `if __name__ == "__main__"` .
+        2. Multiple SummaryCollector instances in callback list are not allowed.
+        3. Not all information is collected at the training phase or at the eval phase.
+        4. SummaryCollector always record the data collected by the summary operator.
+        5. SummaryCollector only supports Linux systems.
+        6. The Summary is not supported when compile source with `-s on` option.
 
     Args:
         summary_dir (str): The collected data will be persisted to this directory.

mindspore/python/mindspore/train/summary/summary_record.py

@@ -101,11 +101,12 @@ class SummaryRecord:
     can be added by calling add_value.
 
     Note:
-        1. Make sure to close the SummaryRecord at the end, otherwise the process will not exit.
+        1. When using SummaryRecord, you need to run the code in `if __name__ == "__main__"` .
+        2. Make sure to close the SummaryRecord at the end, otherwise the process will not exit.
            Please see the Example section below to learn how to close properly in two ways.
-        2. Only one SummaryRecord instance is allowed at a time, otherwise it will cause data writing problems.
-        3. SummaryRecord only supports Linux systems.
-        4. The Summary is not supported when compile source with `-s on` option.
+        3. Only one SummaryRecord instance is allowed at a time, otherwise it will cause data writing problems.
+        4. SummaryRecord only supports Linux systems.
+        5. The Summary is not supported when compile source with `-s on` option.
 
     Args:
         log_dir (str): The log_dir is a directory location to save the summary.