同步操作将从 MindSpore/docs 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
欢迎参与MindSpore文档贡献,符合要求的文档将会在MindSpore官网中呈现。
本项目支持Markdown、reStructuredText和Jupyter Notebook格式的内容贡献,对应地可创建.md
、.rst
和.ipynb
为后缀的文档或修改已存在的文档。
MindSpore docs仓提供了文档写作要求供写作时参考。
如果您发现现有文档需要刷新,可点击页面上方的“View Source on Gitee”(如下图所示),跳转至源文件。修改该文件,并提交PR即可参与贡献。
如果您需要新增文档,请在合适目录新建Markdown或reStructuredText文件,MindSpore docs仓目录结构说明可参考README。
新建文件
新建文件要求如下:
source_zh_cn
目录下,英文文档需新建在source_en
目录下。将新建文件添加到网页
完成写作后,需在网页目录中添加新建的文件。
以训练教程为例,先在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/yes
和ci-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在默认配置的基础上,修改了如下规则:
更为详细规则信息请参考RULES。
PR合入后次日,即可在MindSpore官网中查看到新增内容,新增文档将新建链接。
官网各教程和文档默认选中最新发布版本,如需查看新合入的内容,需在下拉列表中切换至master。
以《初学入门》文档为例,该文档的链接为https://www.mindspore.cn/tutorials/zh-CN/master/beginner/quick_start.html。
MindSpore docs仓提供了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。
修改源文件的注释,并提交PR即可参与贡献。
如果您需要新增API,请先确认是否在已有模块中添加,已有模块列表请查看https://www.mindspore.cn/docs/zh-CN/master/index.html。
如果属于已有模块,在MindSpore代码仓按注释要求完成注释内容,并将该API添加至对应模块的__all__中,确保能通过导入“mindspore.模块名.API名”使用该API。
如果属于以下模块,还需更新MindSpore docs仓的接口列表,请按字母序添加API。
如果不属于已有模块,需新增MindSpore docs仓的接口工程文件,并按字母序添加模块到目录结构中。如需新增mindspore.mindrecord
模块接口,需在docs/docs/api_python/source_zh_cn/mindspore
目录下新增mindspore.mindrecord.rst文件,并将其添加到目录结构中。同时,在docs/docs/api_python/source_en/mindspore
目录下做相应修改,即可生成英文页面内容。
.. toctree::
:maxdepth: 1
:caption: MindSpore Python API
...
mindspore/mindspore.mindrecord
...
完成上述修改,并提交PR即可参与贡献。
提交PR后,需要确保有mindspore-cla/yes
和ci-pipeline-passed
标签,没有stat/need-squash
标签,并经过Committer审核后方可合入。
各标签的详细说明可参见检查文档中的相关内容。
MindSpore CI采用了Pylint检查工具。
为方便查看修改后的API在网页上的显示是否符合预期,MindSpore CI提供了/build_api_doc
命令去构建html:
# 在评论中输入如下命令即可开始构建html
/build_api_doc
执行完成后会返回如下类似结果:
点击zh-CN LINK
可查看中文API构建的html页面,点击EN LINK
可查看英文API构建的html页面。
PR合入后次日,即可在MindSpore官网Python API页面中查看到新增内容。
官网API默认展示最新发布版本,如需查看新合入的内容,如下图所示切换至master分支版本。
文档中的图片主要分为程序流程图、配置流程图和功能结构图等。
具体的作图要求及规范,请参考MindSpore docs仓提供的作图规范。
如果您发现现有文档中的图片需要更新/新增,可点击页面上方的,跳转至源文件。通常图片会存放在./images目录中,只需将需要新增的图片放进这个目录,或将修改后的图片替换原图,并提交PR即可参与贡献。
请同时把原图一并提交到Gitee,放在与存放图片相同的路径下,方便后续修改。
图片引用的格式为:![图片名称](图片所在目录)。详情请参考Markdown图片引用要求和Notebook图片引用要求。
PR合入后次日,即可在MindSpore官网中查看到新增内容,更新/新增图片将会出现在文档中。
官网各教程和文档默认选中最新发布版本,如需查看新合入的内容,需在下拉列表中切换至master。
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。