MindSpore中文API格式规范
类 Class
.. py:class:: Tensor(default_input, dtype=None, init_with_data=True)
Tensor简介。
参数:
- **参数1** (Tensor) – 参数1说明。
- **参数2** (int) – 参数2说明。
- **二级参数1** (int) – 二级参数1说明。(注意:二级参数需要和上面一级参数的“*”对齐。)
- **二级参数2** (int) – 二级参数2说明。
返回:
返回说明。
输入:
- **输入1** (Tensor) - 输入1描述。
- **输入2** (Tensor) - 输入2描述。
输出:
- **输出1** (Tensor) - 输出1描述。
- **输出2** (Tensor) - 输出2描述。
异常:
- **Error1** – 异常描述1。
- **Error1** – 异常描述2。
属性 Property
.. py:method:: T
:property:
返回转置后的张量。
注意:相对于类要增加4空格缩进。
方法 Method
.. py:method:: abs()
方法说明。
返回:
返回说明。
注意:相对于类要增加4空格的缩进。
函数 Function
.. py:function:: name(参数)
描述函数功能。
参数:
- **参数1** (Tensor) – 参数1说明。
- **参数2** (int) – 参数2说明。
返回:
返回说明。
异常:
- **Error1** – 异常描述1。
- **Error1** – 异常描述2。
Note
.. note::
此处描述具体需要注意的部分。
Warning
.. warning::
此处描述具体需要警告的部分。
引入其他部分
.. include:: {relative_file_path.rst}
引用其他.rst
或.txt
文件的内容,其中{relative_file_path.rst}
为待引用文件的相对路径。
注意事项
-
链接的用法:
如果链接文本是网址,语法如下:
`tensor <https://www.gitee.com/mindspore/mindspore/blob/master/mindspore/python/mindspore/common/tensor.py>`_
请注意,链接文本和 URL 的开头 < 之间必须有一个空格,且整体的前后需要有空格。
-
表格的用法:
表格必须包含多行,并且第一列单元格不能包含多行。如下所示:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
-
注意文中专有名词的正确书写,例如“NumPy”,“Python”,“MindSpore”等。
-
以下词请保持英文原词,无需翻译成中文:
a. 参数名称,例如“Args”里面的参数解释。
b. 数据类型,例如:Number, String, Tuple, List, Set, Dictionary, int, float, bool, complex, 等等。
c. 报错和默认值,例如:RuntimeError, ValueError, None, True, False。
d. 一些专有名词,例如:shape, Tensor, Ascend, checkpoint 以及加“ ”,` `, ‘ ’等特殊表示的词。
e. Raises翻译为“异常”。
-
常用特殊字符标记:
- 星号: 写法为: *text* 是强调 (斜体), 效果为:text
- 双星号: 写法为:**text** 重点强调 (加粗), 效果为:text
- 反引号: 写法为:``text`` 代码样式, 效果为:
text
标记需注意的一些限制:
- 不能相互嵌套,例如:``* text*`` 是错误的。
- 内容中间不能有空格: 这样写`` text `` 是错误的。
- 特殊字符标记的前后需要用空格隔开,例如:`init` 的值可以是 `ones` 或 `zeros` 等。
- 如果内容需要特殊字符分隔,使用反斜杠转义。
-
中文API文档中不需要手写“支持平台”和“样例”部分。
-
当前rst文档作为整个API的文档页面时,需要添加标题,且标题名称为当前接口的全名;当前rst文档作为其他rst文档的引用时,不需要添加标题。
-
mindspore.train
和mindspore.nn.transformer
模块下的接口,需要将每个API的文档分别放于train
和transformer
目录下,并在mindspore.train.rst
和mindspore.nn.transformer.rst
文件中通过.. include::
的写法将接口引入过来;其他模块下的接口结构参考英文的API文档。
-
引入类的用法
:class:`类的全称`
a. 引用其他类的内容,类的全称类似于mindspore.nn.Metric,包含一级二级类别的名称。
b. 如果简写为Metric,英文书写为 :class:Metric
,中文书写为 :class:.Metric
,简写中文前面需要加.。
参考