diff --git a/CONTRIBUTING_DOC.md b/CONTRIBUTING_DOC.md index 93f03a5a9af4677495a63b1286a83f5c596992a6..9453ed63d158f21db9acbcda591a6b61f107e77e 100644 --- a/CONTRIBUTING_DOC.md +++ b/CONTRIBUTING_DOC.md @@ -1,5 +1,7 @@ # Contributing Documents +[查看中文](./CONTRIBUTING_DOC_CN.md) + You are welcome to contribute MindSpore documents. Documents that meet requirements will be displayed on the [MindSpore official website](https://www.mindspore.cn). diff --git a/CONTRIBUTING_DOC_CN.md b/CONTRIBUTING_DOC_CN.md new file mode 100644 index 0000000000000000000000000000000000000000..914ba5b6e5820fe8fd1441df90507ca55fd3d1c2 --- /dev/null +++ b/CONTRIBUTING_DOC_CN.md @@ -0,0 +1,92 @@ +# 贡献文档 + +[View English](./CONTRIBUTING_DOC.md) + +欢迎参与MindSpore文档贡献,符合要求的文档将会在[MindSpore官网](http://www.mindspore.cn)中呈现。 + + + +- [贡献文档](#贡献文档) + - [新建或更新文档](#新建或更新文档) + - [提交修改](#提交修改) + - [文档写作规范](#文档写作规范) + + + +## 新建或更新文档 + +本项目支持MarkDown和reStructuredText格式的内容贡献,对应地可创建```.md```和```.rst```为后缀的文档或修改已存在的文档。 + +## 提交修改 + +提交修改的步骤与代码相同,请参考[代码贡献指南](https://gitee.com/mindspore/mindspore/blob/master/CONTRIBUTING.md)。 + +## 文档写作规范 + +- 标题仅支持Atx风格,标题与上下文需用空行隔开。 + + ``` + # 一级标题 + + ## 二级标题 + + ### 三级标题 + ``` + +- 列表标题和内容如需换行显示,标题和内容间需增加一个空行,否则无法实现换行。 + + ``` + - 标题 + + 内容。 + ``` + +- 目录中的锚点(超链接)只能使用中文、小写英文字母或“-”,不能带有空格或其他特殊字符,否则会导致链接无效。 + +- 注意事项使用“>”标识。 + + ``` + > 注意事项内容。 + ``` + +- 参考文献需列举在文末,并在文中标注。 + + ``` + 引用文字或图片说明后,增加标注[编号]。 + + ## 参考文献 + + [1] 作者. [有链接的文献名](http://xxx). + + [2] 作者. 没有链接的文献名. + ``` + +- 示例代码注释需遵循如下要求: + + - 注释用英文写作; + - Python函数、方法、类的注释使用```"""```; + - Python其他代码注释使用```#```; + - C++代码注释使用```//```。 + + ``` + """ + Python函数、方法、类的注释 + """ + + # Python代码注释 + + // C++代码注释 + + ``` + +- 图和图标题前后需增加一个空行,否则会导致排版异常。 + + ``` + 如下图所示: + + ![](./xxx.png) + + 图1:xxx + + 下文内容。 + ``` \ No newline at end of file diff --git a/README.md b/README.md index 9957788d3a2e7bf8bac9febb56dfc55eea2574a8..fe8f90ffeaad28d4c66d0c4672bae86222f5f3db 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ -# MindSpore Documents +# MindSpore Documents ![MindSpore Logo](resource/MindSpore-logo.png) +[查看中文](./README_CN.md) + ## Overview This project provides the source files of the installation guide, tutorials, and other documents, as well as API configurations on the MindSpore official website . @@ -50,4 +52,4 @@ MindSpore tutorials and API documents can be generated by [Sphinx](https://www.s ## License - [Apache License 2.0](LICENSE) -- [Creative Commons License version 4.0](LICENSE-CC-BY-4.0) +- [Creative Commons License version 4.0](LICENSE-CC-BY-4.0) \ No newline at end of file diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 0000000000000000000000000000000000000000..b65ca489d3fd8d94724839fa5fb4f277968106c1 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,55 @@ +# MindSpore文档 + +![MindSpore Logo](resource/MindSpore-logo.png) + +[View English](./README.md) + +## 简介 + +此工程提供MindSpore官方网站所呈现安装指南、教程、文档的源文件以及API的相关配置。 + +## 贡献 + +我们非常欢迎您贡献文档!如果想要参与,请阅读[CONTRIBUTING_DOC_CN.md](./CONTRIBUTING_DOC_CN.md),务必遵守文档写作规范,并按照流程规则提交,审核通过后,改动会在文档工程和官网中呈现。 + +同时,如果您对文档有任何意见或建议,请在Issues中提交。 + +## 目录结构说明 + +``` +docs +├───api //用于生成API的相关配置文件 +│ +├───docs //介绍文档 +│ +├───install //安装指南 +│ +├───resource //资源相关文档 +│ +├───tutorials //教程相关文档 +│ +└───README.md //Docs仓说明 +``` + +## 文档构建 + +MindSpore的教程和API文档均可由[Sphinx](https://www.sphinx-doc.org/en/master/)工具生成。下面以API文档为例介绍具体步骤。 + +1. 下载MindSpore Docs仓代码。 + ```shell + git clone https://gitee.com/mindspore/docs.git + ``` +2. 进入docs目录,安装该目录下```requirements.txt```文件中的依赖项。 + ```shell + cd docs/api + pip install -r requirements.txt + ``` +3. 在docs目录下执行如下命令,完成后会新建build_zh_cn/html目录,该目录中存放了生成后的文档网页,打开```build_zh_cn/html/index.html```即可查看API文档内容。 + ``` + make html + ``` + +## 版权 + +- [Apache License 2.0](LICENSE) +- [Creative Commons License version 4.0](LICENSE-CC-BY-4.0)