diff --git a/guidelines/docs_api_checklist.md b/guidelines/docs_api_checklist.md new file mode 100644 index 0000000..8ec3de5 --- /dev/null +++ b/guidelines/docs_api_checklist.md @@ -0,0 +1,45 @@ +# MindSpore API Checklist + +本文档为API接口文档的测试和开发提供检查依据,保证API接口功能描述的完备性、输入输出参数和示例代码的正确性。 + +API样例:[mindspore.nn.Conv1d](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Conv1d.html#mindspore.nn.Conv1d)、[mindspore.nn.Momentum](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Momentum.html#mindspore.nn.Momentum)、[mindspore.nn.Dropout](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/nn/mindspore.nn.Dropout.html#mindspore.nn.Dropout)、[mindspore.ops.Conv2D](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/ops/mindspore.ops.Conv2D.html#mindspore.ops.Conv2D)、[mindspore.dataset.MnistDataset](https://www.mindspore.cn/docs/api/zh-CN/master/api_python/dataset/mindspore.dataset.MnistDataset.html#mindspore.dataset.MnistDataset) + +| 类别 | 检查点 | 注意要点 | +| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 接口名称 | 接口名称 | 接口是否缺失,即未在API页面展示。(教程中提到的接口都应在API文档中能查到) | +| 接口描述 | 描述准确完整 | **普通接口要求:**
1. 描述该接口功能、使用场景和约束(接口间的依赖关系)等。
2. 对于使用方式较复杂的接口,应该在文档中详细说明该接口的使用方法和约束。
3. 提及的变量能否在本接口或其他接口中找到说明:没有的需要补充或提供可以参考哪里。
**算子补充要求:
** 1. 每个算子都要描述下这个算子的数学含义,包括做什么、怎么计算的等。如果无法描述清楚,需要使用公式说明。
2. 复杂的算子接口可在注释中提供多个例子。 | +| | 公式 | 数学运算相关算子给出对应的公式,注意公式的引用是否合理,显示是否有问题。 | +| Parameters(算子不涉及) | 参数个数 | 参数个数是否完全和源码中的所有参数对应。 | +| | 参数默认值/取值范围 | 1. 参数存在默认值/取值范围的话,是否给出描述,是否和源码中一致。
2. 默认值/取值范围的含义和可能的关联关系(参数间的依赖关系)是否清晰。 | +| | 参数数据类型是否链接到相应网址 | 基本数据类型:int、float、bool、str、list、dict、set、tuple。
其他数据类型:mindspore.dtype、numpy.dtype等。 | +| Returns(算子不涉及) | 返回值 | 返回值类型和含义是否正确。 | +| Inputs(算子特有) | 算子输入 | 描述算子的输入类型和shape。
注意输入类型是否正确。类型是Tensor时,需描述shape,并按:math:\`(N, C, X)\`格式写作。 | +| Outputs(算子特有) | 算子输出 | 描述算子的输出类型和shape。
注意输出类型是否正确。类型是Tensor时,需描述shape,并按:math:\`(N, C, X)\`格式写作。 | +| Note | 特殊说明 | 说明内容是否是用户需特别关注的点,是否准确,是否有遗漏,样式是否正确。 | +| Warning | 告警说明 | 1. 是否描述了使用该接口时需要警告的事项,以免造成负面影响。
2. 实验阶段的API是否有说明。 | +| Raises | 异常 | 建议描述关键异常的影响和处理方案(其他异常将在代码报错信息上指导用户)。 | +| Examples | 示例是否典型、完整、可运行 | 示例代码需要典型、完整而且正确运行,要展示输出结果或维度等信息。 | +| 展示效果 | 链接 | 引用的链接是否正常,如论文链接。 | +| | 专有术语 | 是否按照[术语表](https://www.mindspore.cn/docs/zh-CN/master/design/glossary.html)书写。如:LeNet、Ascend等。 | + +中文API补充Checklist: + +1. 是否存在翻译不合适的词:判断是否需要翻译,如需翻译应翻译成什么。 + +2. 是否存在一致性问题。 + + - 公式和参数不一致。 + - 中文和英文不一致。 + - 描述同一内容时,翻译词汇不一致。 + - 描述同一内容时,大小写、中划线、下划线、空格等不一致。 + - 同一类型内容使用的引号不一致(单引、双引或`)。 + +3. 标点是否有误用。 + + - 所有变量或接口是否都使用`包裹。 + - 变量值是否都使用单引或双引包裹,且引号统一为英文符号。 + - 描述语句中是否存在英文的逗号、分号、句号等。 + - 并列关系时是否使用顿号隔开。 + +4. 中文、英文全称、英文缩写描述是否合理。 +5. Tensor、Python、True、False、None等注意大小写。 diff --git a/security/comments_specification_en.md b/guidelines/docs_comments_guidelines_en.md similarity index 100% rename from security/comments_specification_en.md rename to guidelines/docs_comments_guidelines_en.md diff --git a/security/comments_specification_zh_cn.md b/guidelines/docs_comments_guidelines_zh_cn.md similarity index 100% rename from security/comments_specification_zh_cn.md rename to guidelines/docs_comments_guidelines_zh_cn.md diff --git a/guidelines/docs_guidelines.md b/guidelines/docs_guidelines.md new file mode 100644 index 0000000..e4e85c4 --- /dev/null +++ b/guidelines/docs_guidelines.md @@ -0,0 +1,7 @@ +# MindSpore文档写作规范 + +| 文档类型 | 内容要求 | 格式要求 | +| --- | --- | --- | +| 开发指南(含教程、编程指南等文档)| - 每篇文档需要包括**开发概述**、**开发任务**和**样例代码**三部分。
- 所有文档需有完整可运行的代码,文档只允许以下两种方式:
1. Notebook(可一键运行)
2. Markdown+可一键运行的完整代码/代码工程 | - [Notebook](./docs_notebook_guidelines.md)
- [Markdown](./docs_markdown_guidelines.md)| +| API描述 | [API Checklist](./docs_api_checklist.md) | - [中文](./docs_zh_api_guidelines.md)
- [英文](./docs_comments_guidelines_zh_cn.md) | +| 样例代码(含开发指南和API)| 典型、完整、可运行、易复现、没有WARNING/ERROR信息 | - [import方式推荐](./docs_import.md) | diff --git a/guidelines/docs_import.md b/guidelines/docs_import.md new file mode 100644 index 0000000..9a32379 --- /dev/null +++ b/guidelines/docs_import.md @@ -0,0 +1,36 @@ +# MindSpore import方式推荐 + +文档样例代码推荐采用以下import方式编写。 + +```python +import mindspore as ms +import mindspore.dataset as ds +import mindspore.dataset.audio as audio +import mindspore.dataset.text as text +import mindspore.dataset.transforms as transforms +import mindspore.dataset.vision as vision +from mindspore.mindrecord import FileWriter +import mindspore.communication as comm +import mindspore.nn as nn +import mindspore.ops as ops +import mindspore.numpy as mnp +import mindspore.scipy as mscipy +import mindspore.boost as boost + +import mindspore.nn.probability.bijector as bijector +import mindspore.nn.probability.distribution as distribution + +import numpy as np +``` + +代码写作样例如下: + +```python +ms.common.initializer.xxx +ms.Tensor +ms.Parameter +ms.Model +ms.float32 +ms.set_context +nn.transformer.xxx +``` diff --git a/guidelines/docs_markdown_guidelines.md b/guidelines/docs_markdown_guidelines.md new file mode 100644 index 0000000..86411e4 --- /dev/null +++ b/guidelines/docs_markdown_guidelines.md @@ -0,0 +1,246 @@ +# MindSpore Markdown文档写作要求 + + + +- [MindSpore Markdown文档写作要求](#mindspore-markdown文档写作要求) + - [文档命名](#文档命名) + - [标题](#标题) + - [gitee链接](#gitee链接) + - [概述](#概述) + - [注意事项](#注意事项) + - [有序/无序列表](#有序无序列表) + - [代码样例](#代码样例) + - [图片](#图片) + - [表格](#表格) + - [术语](#术语) + - [参考文献](#参考文献) + - [格式](#格式) + - [英文](#英文) + + + +## 文档命名 + +Markdown文件名和图片名使用全小写,单词间可使用_分隔。 + +## 标题 + +- 标题仅支持Atx风格,标题与上下文需用空行隔开。 +- 标题最多不超过4级(####)。 + +示例: + +```text +# 一级标题 + +## 二级标题 + +### 三级标题 +``` + +## gitee链接 + +每个Markdown文件添加链到自身的gitee链接,方便在网页上直接跳转到gitee页面。 + +- 文中使用gitee链接时,目录应为`https://gitee.com/mindspore/docs/tree/xxx`,文件应为`https://gitee.com/mindspore/docs/blob/xxx`。 + +示例: + +```markdown + +``` + +## 概述 + +要求描述以下内容: + +- 主题内容相关技术的背景、介绍以及给用户带来的好处。 +- MindSpore在各平台的支持情况。 +- 完整样例代码的链接。 + +## 注意事项 + +注意事项使用“>”标识。 + +示例: + +```text +> 注意事项内容。 +``` + +多条示例: + +```text +> - 注意事项内容。 +> - 注意事项内容。 +``` + +受Sphinx工具解析限制,注意事项中只能列举单行代码。 + +```text +> 注意事项内容,`code`。 +``` + +## 有序/无序列表 + +- 有序/无序列表下的详细内容需缩进4格写作。 +- 标题和内容间需增加一个空行,否则可能无法实现换行。 + +示例: + +````text +1. 内容1。 + + 详细说明。 + + ``` + code + ``` + +2. 内容2。 + + 详细说明。 + + ``` + code + ``` + +```` + +````text +- 内容1。 + + 详细说明。 + + ``` + code + ``` + +- 内容2。 + + 详细说明。 + + ``` + code + ``` + +```` + +## 代码样例 + +- 教程和文档中不可出现下划线开头的内部接口。 +- 注释要求使用英文写作。 +- Python函数、方法、类的注释使用```"""```。 +- Python其他代码注释使用```#```。 +- C++代码注释使用```//```。 + +示例: + +```text +""" +Python函数、方法、类的注释 +""" + +# Python代码注释 + +// C++代码注释 + +``` + +## 图片 + +- 教程和文档的图片中不出现个人信息。 +- 采用Markdown格式写,不要采用html格式写。 +- 图和上下文需增加一个空行,否则会导致排版异常。 +- 图片放置在临近的images目录下。 + +示例: + +```text +![xxx](./xxx.png) +``` + +## 表格 + +- 表格前后需增加一个空行,否则会导致排版异常。 +- 采用Markdown格式写,不要采用html格式写。 +- 有序或无序列表内不支持表格。 + +示例: + +```text +## 文章标题 + +| 表头1 | 表头2 +| ----- | ---- +| 内容I1 | 内容I2 +| 内容II1 | 内容II2 + +下文内容。 +``` + +## 术语 + +统一术语大小写:MindSpore、CIFAR-10、Python等。详见[术语表](https://www.mindspore.cn/docs/zh-CN/master/design/glossary.html)。 + +## 参考文献 + +- 参考文献需列举在文末,并在文中标注。 +- 引用文字或图片说明后,增加标注[编号]。 + +示例: + +```text +## 参考文献 + +[1] 作者. [有链接的文献名](http://xxx). + +[2] 作者. 没有链接的文献名. +``` + +## 格式 + +- 教程、文档中引用接口、路径名、文件名等使用“\` \`”标注,如果是函数或方法,最后不加括号。 + + 引用方法示例: + + ```text + 使用映射 `map` 方法。 + ``` + + 引用代码示例: + + ```text + `batch_size`:每组包含的数据个数。 + ``` + + 引用路径示例: + + ```text + 将数据集解压存放到工作区`./MNIST_Data`路径下。 + ``` + + 引用文件名示例: + + ```text + 其他依赖项在`requirements.txt`中有详细描述。 + ``` + +- 教程、文档中待用户替换的内容需要额外标注,在正文中,使用“*”包围需要替换内容,在代码片段中,使用“{}”包围替换内容。 + + 正文中示例: + + ```text + 需要替换你的本地路径*your_path*。 + ``` + + 代码片段中示例: + + ```text + conda activate {your_env_name} + ``` + +## 英文 + +- 中英文内容需同步修改。 +- 英文文档需链英文链接。如将`zh-CN`改成`en`。 diff --git a/guidelines/docs_notebook_guidelines.md b/guidelines/docs_notebook_guidelines.md new file mode 100644 index 0000000..58f0839 --- /dev/null +++ b/guidelines/docs_notebook_guidelines.md @@ -0,0 +1,127 @@ +# MindSpore Notebook文档写作要求 + + + +- [MindSpore Notebook文档写作要求](#mindspore-notebook文档写作要求) + - [文档命名](#文档命名) + - [单元格组成](#单元格组成) + - [内容大纲](#内容大纲) + - [文档相关文件存放](#文档相关文件存放) + - [图片](#图片) + - [表格](#表格) + - [其他](#其他) + + + +## 文档命名 + +ipynb文件名和图片名使用全小写,单词间可使用_分隔。 + +## 单元格组成 + +Notebook文档使用Markdown和运行代码两种单元格组合的形式。 + +- Markdown单元格格式要求参考[MindSpore Markdown文档写作要求](./docs_markdown_guidelines.md)。 +- 运行代码单元格格式要求参考编码规范。 + +## 内容大纲 + +1. 标题(与当前主题相关):`# xxxx`。 +2. 作者:名字加Gitee或Github个人链接。 +3. 资源链接标签:使用“图片+链接”的格式,` `表示分隔符。 + + 如: + + ```text + [![在线运行](https://gitee.com/mindspore/docs/raw/master/resource/_static/logo_modelarts.png)](https://authoring-modelarts-cnnorth4.huaweicloud.com/console/lab?share-url-b64=aHR0cHM6Ly9taW5kc3BvcmUtd2Vic2l0ZS5vYnMuY24tbm9ydGgtNC5teWh1YXdlaWNsb3VkLmNvbS9ub3RlYm9vay9tb2RlbGFydHMvbWluZHNwb3JlX3F1aWNrX3N0YXJ0LmlweW5i&imageid=65f636a0-56cf-49df-b941-7d2a07ba8c8c) [![下载Notebook](https://gitee.com/mindspore/docs/raw/master/resource/_static/logo_notebook.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/master/tutorials/zh_cn/beginner/mindspore_quick_start.ipynb) [![下载样例代码](https://gitee.com/mindspore/docs/raw/master/resource/_static/logo_download_code.png)](https://obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/master/tutorials/zh_cn/beginner/mindspore_quick_start.py) [![查看源文件](https://gitee.com/mindspore/docs/raw/master/resource/_static/logo_source.png)](https://gitee.com/mindspore/docs/blob/master/tutorials/source_zh_cn/beginner/quick_start.ipynb) + ``` + + 每个链接构成的方法如下: + + - 在线运行: + + ```text + authoring-modelarts-cnnorth4.huaweicloud.com/console/lab?share-url-bs64={Notebook存储地址的base64编码}&image_id={镜像id} + ``` + + - 下载Notebook: + + ```text + obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/{Gitee中docs仓的分支}/{中文zh_cn/英文en}/{Gitee仓库中该Notebook的地址} + ``` + + - 下载样例代码: + + ```text + obs.dualstack.cn-north-4.myhuaweicloud.com/mindspore-website/notebook/{Gitee中docs仓的分支}/{中文zh_cn/英文en}/{Gitee仓库中该Notebook对应的py文件地址} + ``` + + 后缀由.ipynb改为.py。 + + - 查看源文件:Gitee仓库中该Notebook文件的地址。 + +4. 概述。 +5. 整体流程。 +6. 说明(完整样例代码地址、硬件/系统/平台支持情况)。 +7. 准备环节:包括环境配置信息等。 +8. 数据集加载、导入公共模块(非必要的话尽量和使用到的代码放在一起)。 +9. 数据预处理。 +10. 文档主要内容:进行训练、验证精度等。 +11. 总结(与当前主题相关)。 + +补充说明: + +- 整体结构可以参考[快速入门](https://gitee.com/mindspore/docs/blob/master/tutorials/source_zh_cn/beginner/quick_start.ipynb)。 +- 内容中不要含有个人信息(可以在文件开头附加作者和个人链接)。 +- 每个代码单元格建议有输出结果展示,帮助用户加深理解。 +- 要求可全文档一键重复多次运行(注意:需编写相关代码在重复运行时删除过期或无效的相关文件)。 + +## 文档相关文件存放 + +1. 文中使用到的数据集需要提供可下载的链接地址。 + +2. 代码中相关文件存放的路径(供参考,可根据实际情况调整): + + - 训练的模型路径设置为:`./model/{模型文件类型}/{ipynb的文件名}/{模型文件}`。 + + 常用的模型文件类型有: + + - `ckpt`:CheckPoint格式文件。 + - `mindir`:MindIR格式文件。 + - `onnx`:ONNX格式文件。 + - `air`:AIR格式文件。 + - 数据集放置位置设置为: + + - 常用数据集: + + - 常用数据集路径写为:`./datasets/{数据集名称}/{数据文件}`。 + - 训练数据集路径写为:`./datasets/{ipynb的文件名}/{数据集名称}/train/{数据文件}`。 + - 测试数据集路径写为:`./datasets/{ipynb的文件名}/{数据集名称}/test/{数据文件}`。 + - 自定义数据集: + + - 单张图片的存放 + + 例如 `test.jpg`文件,放置路径:`./datasets/{ipynb的文件名}/images/test.jpg`。 + - 单个文件的存放 + + 例如 `test.csv`文件,放置路径:`./datasets/{ipynb的文件名}/docs/test.csv`。 + - MindRecord数据放置 + + 原始MindRecord数据放置在:`./datasets/{ipynb的文件名}/mindrecord/{数据文件}`。 + + 其他数据转换为MindRecord的,放置在:`./datasets/{ipynb的文件名}/ds_to_mindrecord/{数据文件}`。 + + MindRecord转换成其他数据,放置在:`./datasets/{ipynb的文件名}/mindrecord_to_ds/{数据文件}`。 + +## 图片 + +1. 文中所引用的所有图片或其他资源文件需使用**绝对路径**,不使用相对链接,**图片名称不能包含下划线**。 +2. 所引用的图片、链接、文档、代码、数据集无版权问题。 + +## 表格 + +文中的表格使用Markdown写法,需要确保每行上下的格式符号“|”对齐,且符号“:---------”的长度超过表中该列的最长部分。 + +## 其他 + +display_name设置为MindSpore,name设置为mindspore,便于直接对接在线体验环境。 diff --git a/guidelines/docs_zh_api_guidelines.md b/guidelines/docs_zh_api_guidelines.md new file mode 100644 index 0000000..5b0238e --- /dev/null +++ b/guidelines/docs_zh_api_guidelines.md @@ -0,0 +1,173 @@ +# MindSpore中文API格式规范 + +## 类 Class + +```text +.. 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 + +```text +.. py:method:: T + :property: + + 返回转置后的张量。 +``` + +注意:相对于类要增加4空格缩进。 + +## 方法 Method + +```text +.. py:method:: abs() + + 方法说明。 + + 返回: + 返回说明。 +``` + +注意:相对于类要增加4空格的缩进。 + +## 函数 Function + +```text +.. py:function:: name(参数) + + 描述函数功能。 + + 参数: + - **参数1** (Tensor) – 参数1说明。 + - **参数2** (int) – 参数2说明。 + + 返回: + 返回说明。 + + 异常: + - **Error1** – 异常描述1。 + - **Error1** – 异常描述2。 +``` + +## Note + +```text +.. note:: + 此处描述具体需要注意的部分。 +``` + +## Warning + +```text +.. warning:: + 此处描述具体需要警告的部分。 +``` + +## 引入其他部分 + +```text + +.. include:: {relative_file_path.rst} + +``` + +引用其他`.rst`或`.txt`文件的内容,其中`{relative_file_path.rst}`为待引用文件的相对路径。 + +## 注意事项 + +1. 链接的用法: + + 如果链接文本是网址,语法如下: + + ```text + `tensor `_ + ``` + + 请注意,链接文本和 URL 的开头 < 之间必须有一个空格,且整体的前后需要有空格。 + +2. 表格的用法: + + 表格必须包含多行,并且第一列单元格不能包含多行。如下所示: + + ```text + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + ``` + +3. 注意文中专有名词的正确书写,例如“NumPy”,“Python”,“MindSpore”等。 + +4. 以下词请保持英文原词,无需翻译成中文: + + 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翻译为“异常”。 + +5. 常用特殊字符标记: + + - 星号: 写法为: \*text\* 是强调 (斜体), 效果为:*text* + - 双星号: 写法为:\*\*text\*\* 重点强调 (加粗), 效果为:**text** + - 反引号: 写法为:\`\`text\`\` 代码样式, 效果为:``text`` + + 标记需注意的一些限制: + + - 不能相互嵌套,例如:\`\`\* text\*\`\` 是错误的。 + - 内容中间不能有空格: 这样写\`\` text \`\` 是错误的。 + - 特殊字符标记的前后需要用空格隔开,例如:\`init\` 的值可以是 \`ones\` 或 \`zeros\` 等。 + - 如果内容需要特殊字符分隔,使用反斜杠转义。 + +6. 中文API文档中不需要手写“支持平台”和“样例”部分。 +7. 当前rst文档作为整个API的文档页面时,需要添加标题,且标题名称为当前接口的全名;当前rst文档作为其他rst文档的引用时,不需要添加标题。 +8. `mindspore.train`和`mindspore.nn.transformer`模块下的接口,需要将每个API的文档分别放于`train`和`transformer`目录下,并在`mindspore.train.rst`和`mindspore.nn.transformer.rst`文件中通过`.. include::`的写法将接口引入过来;其他模块下的接口结构参考英文的API文档。 + +9. 引入类的用法 + + ```text + + :class:`类的全称` + + ``` + + a. 引用其他类的内容,类的全称类似于mindspore.nn.Metric,包含一级二级类别的名称。 + + b. 如果简写为Metric,英文书写为 :class:`Metric`,中文书写为 :class:`.Metric`,简写中文前面需要加.。 + +## 参考 + +- 有关rst的书写规则,请参考[rst入门](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)。 +- 有关rst在Python领域的用法,请参考[rst在Python领域用法](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-python-domain)。