diff --git a/CONTRIBUTING_DOC.md b/CONTRIBUTING_DOC.md index 93f03a5a9af4677495a63b1286a83f5c596992a6..bcbe478c9e7467d9dd5d803dde7a0c2b447320c1 100644 --- a/CONTRIBUTING_DOC.md +++ b/CONTRIBUTING_DOC.md @@ -47,6 +47,8 @@ The procedure for submitting the modification is the same as that for submitting > Precautions ``` +- Please use the formula symbol $reasonably, and ' ' 'is recommended for non-formula special marks. + - References should be listed at the end of the document and marked in the document. ``` @@ -88,3 +90,4 @@ The procedure for submitting the modification is the same as that for submitting The following content. ``` +[跳转中文文档](/CONTRIBUTING_DOC_CN.md) \ No newline at end of file diff --git a/CONTRIBUTING_DOC_CN.md b/CONTRIBUTING_DOC_CN.md new file mode 100644 index 0000000000000000000000000000000000000000..c366de7e6f6b7fbd1901b515cff6a7f8ecca71d8 --- /dev/null +++ b/CONTRIBUTING_DOC_CN.md @@ -0,0 +1,93 @@ +# 贡献文档 + +欢迎参与MindSpore文档贡献,符合要求的文档将会在[MindSpore官网](http://www.mindspore.cn)中呈现。 + + + +- [贡献文档](#贡献文档) + - [新建或更新文档](#新建或更新文档) + - [提交修改](#提交修改) + - [文档写作规范](#文档写作规范) + + + +## 新建或更新文档 + +本项目支持MarkDown和reStructuredText格式的内容贡献,对应地可创建```.md```和```.rst```为后缀的文档或修改已存在的文档。 + +## 提交修改 + +提交修改的步骤与代码相同,请参考[代码贡献指南](./CONTRIBUTING_CODE.md)。 + +## 文档写作规范 + +- 标题仅支持Atx风格,标题与上下文需用空行隔开。 + + ``` + # 一级标题 + + ## 二级标题 + + ### 三级标题 + ``` + +- 列表标题和内容如需换行显示,标题和内容间需增加一个空行,否则无法实现换行。 + + ``` + - 标题 + + 内容。 + ``` + +- 目录中的锚点(超链接)只能使用中文、小写英文字母或“-”,不能带有空格或其他特殊字符,否则会导致链接无效。 + +- 注意事项使用“>”标识。 + + ``` + > 注意事项内容。 + ``` + +- 请合理使用公式符号$,非公式的特殊标记建议使用```。 + +- 参考文献需列举在文末,并在文中标注。 + + ``` + 引用文字或图片说明后,增加标注[编号]。 + + ## 参考文献 + + [1] 作者. [有链接的文献名](http://xxx). + + [2] 作者. 没有链接的文献名. + ``` + +- 示例代码注释需遵循如下要求: + + - 注释用英文写作; + - python函数、方法、类的注释使用```"""```; + - python其他代码注释使用```#```; + - c++代码注释使用```//```。 + + ``` + """ + python函数、方法、类的注释 + """ + + # python代码注释 + + // c++代码注释 + + ``` + +- 图和图标题前后需增加一个空行,否则会导致排版异常。 + + ``` + 如下图所示: + + ![](./xxx.png) + + 图1:xxx + + 下文内容。 + ``` + [跳转英文文档](/CONTRIBUTING_DOC.md) \ No newline at end of file diff --git a/README.md b/README.md index 9957788d3a2e7bf8bac9febb56dfc55eea2574a8..4f88b8998dbe6d9bf6a03c5e6a182a3d30f5062d 100644 --- a/README.md +++ b/README.md @@ -50,4 +50,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_Docs_CN.md b/README_Docs_CN.md new file mode 100644 index 0000000000000000000000000000000000000000..ce2227c001057de5d2e91f2e19c9c6afae273c3e --- /dev/null +++ b/README_Docs_CN.md @@ -0,0 +1,53 @@ +# MindSpore文档 + +![MindSpore Logo](resource/MindSpore-logo.png) + +[跳转英文文档](/README.md) + +## 简介 + +此工程提供MindSpore官方网站所呈现安装指南、教程、文档的源文件以及API的相关配置。 + +## 贡献 + +我们非常欢迎您贡献文档!如果想要参与,请阅读[CONTRIBUTING_DOC.md](./CONTRIBUTING_DOC_CN.md),务必遵守文档写作规范,并按照流程规则提交,审核通过后,改动会在文档工程和官网中呈现。 + +同时,如果您对文档有任何意见或建议,请在Issues中提交。 + +## 目录结构说明 + +``` +docs +├───docs //介绍文档和API生成的相关配置文件 +│ +├───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/docs + 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)