Skip to content

Latest commit

 

History

History
182 lines (105 loc) · 10.6 KB

CONTRIBUTING_DOC_CN.md

File metadata and controls

182 lines (105 loc) · 10.6 KB

贡献文档

View English

欢迎参与MindSpore文档贡献,符合要求的文档将会在MindSpore官网中呈现。

本项目支持Markdown、reStructuredText和Jupyter Notebook格式的内容贡献,对应地可创建.md.rst.ipynb为后缀的文档或修改已存在的文档。

文档

MindSpore docs仓提供了文档写作要求供写作时参考。

更新/新增文档

更新文档

如果您发现现有文档需要刷新,可点击页面上方的“View Source on Gitee”(如下图所示),跳转至源文件。修改该文件,并提交PR即可参与贡献。

View Source on Gitee

新增文档

如果您需要新增文档,请在合适目录新建Markdown或reStructuredText文件,MindSpore docs仓目录结构说明可参考README

  1. 新建文件

    新建文件要求如下:

    • 存放路径:中文文档需新建在source_zh_cn目录下,英文文档需新建在source_en目录下。
    • 文件名:文件名需由英文小写或下划线组成。
  2. 将新建文件添加到网页

    完成写作后,需在网页目录中添加新建的文件。

    以训练教程为例,先在source_zh_cn目录下找到index.rst文件,该文件即对应训练教程网页的组织结构。

    在对应的分类中添加新建的文件,也可新建分类后再添加。以《实现一个图片分类应用》文档为例,该文档存放在quick_start目录,命名为quick_start.md,需将quick_start/quick_start添加至“快速入门”分类下,如下所示。

    .. toctree::
      :glob:
      :maxdepth: 1
      :caption: 快速入门
      :hidden:
    
      quick_start/quick_start
      quick_start/linear_regression
      quick_start/quick_video

完成上述操作后,并提交PR即可参与贡献。

检查文档

提交PR后,需要确保有mindspore-cla/yesci-pipeline-passed标签,没有stat/need-squash标签,并经过Committer审核后方可合入。

  • mindspore-cla/yes:表示已正确签署CLA。如果已签署,系统会自动添加该标签。如果没有签署,系统会自动添加mindspore-cla/no标签,签署完后在PR下添加评论/check-cla,即可自动添加mindspore-cla/yes标签。
  • ci-pipeline-passed:表示已通过MindSpore CI检查。创建PR时,MindSpore CI会自动启动检查,如果已检查通过,系统会自动添加该标签。如果没有检查通过,系统会自动添加ci-pipeline-failed标签,问题修改完后在PR下添加评论/retest,检查通过即可自动添加ci-pipeline-passed标签。
  • stat/need-squash:表示该PR存在多次提交记录,需通过git rebase操作整合成一次提交记录后,才可自动删除该标签。

MindSpore CI采用了Markdownlint、Pylint、Shellcheck、Cppcheck、Cpplint、Tab等检查工具。

其中,Markdownlint是一款检查Markdown文件格式正确性的工具,可以根据设置的规则以及创建的新规则对Markdown文件进行全面的检查。MindSpore CI在默认配置的基础上,修改了如下规则:

  • MD007(无序列表缩进)规则将参数indent设置为4,表示无序列表内的所有内容需缩进4格写作。
  • MD009(行尾空格)规则将参数br_spaces设置为2,表示行尾可以有0个或2个空格。
  • MD029(有序列表的前缀序号)规则将参数style设置为ordered,表示有序列表的前缀序号需按顺序递增。

更为详细规则信息请参考RULES

确认内容

PR合入后次日,即可在MindSpore官网中查看到新增内容,新增文档将新建链接。

官网各教程和文档默认选中最新发布版本,如需查看新合入的内容,需在下拉列表中切换至master。

master_doc

以《初学入门》文档为例,该文档的链接为https://www.mindspore.cn/tutorials/zh-CN/master/beginner/quick_start.html

API

MindSpore docs仓提供了API注释写作要求供写作时参考。

更新/新增API

更新Python API

如果您发现现有API需要刷新,请先在MindSpore代码中找到该接口所在的源文件。

如果不清楚所在文件,可点击“source”,并参考跳转的链接地址中_modules后的内容,找到该文件。

以Tensor为例,点击“source”后得到地址https://www.mindspore.cn/docs/en/master/_modules/mindspore/common/tensor.html#Tensor,源文件地址即为https://gitee.com/mindspore/mindspore/blob/master/mindspore/python/mindspore/common/tensor.py

API Source

修改源文件的注释,并提交PR即可参与贡献。

新增Python API

如果您需要新增API,请先确认是否在已有模块中添加,已有模块列表请查看https://www.mindspore.cn/docs/zh-CN/master/index.html

完成上述修改,并提交PR即可参与贡献。

检查Python API

提交PR后,需要确保有mindspore-cla/yesci-pipeline-passed标签,没有stat/need-squash标签,并经过Committer审核后方可合入。

各标签的详细说明可参见检查文档中的相关内容。

MindSpore CI采用了Pylint检查工具。

预览Python API

为方便查看修改后的API在网页上的显示是否符合预期,MindSpore CI提供了/build_api_doc命令去构建html:

# 在评论中输入如下命令即可开始构建html
/build_api_doc

执行完成后会返回如下类似结果:

build_api_doc

点击zh-CN LINK可查看中文API构建的html页面,点击EN LINK可查看英文API构建的html页面。

确认内容

PR合入后次日,即可在MindSpore官网Python API页面中查看到新增内容。

官网API默认展示最新发布版本,如需查看新合入的内容,如下图所示切换至master分支版本。

master_api

作图

文档中的图片主要分为程序流程图、配置流程图和功能结构图等。

具体的作图要求及规范,请参考MindSpore docs仓提供的作图规范

更新/新增图片

如果您发现现有文档中的图片需要更新/新增,可点击页面上方的View Source on Gitee,跳转至源文件。通常图片会存放在./images目录中,只需将需要新增的图片放进这个目录,或将修改后的图片替换原图,并提交PR即可参与贡献。

请同时把原图一并提交到Gitee,放在与存放图片相同的路径下,方便后续修改。

图片引用

图片引用的格式为:![图片名称](图片所在目录)。详情请参考Markdown图片引用要求Notebook图片引用要求

确认内容

PR合入后次日,即可在MindSpore官网中查看到新增内容,更新/新增图片将会出现在文档中。

官网各教程和文档默认选中最新发布版本,如需查看新合入的内容,需在下拉列表中切换至master。

master_doc