文档编写规范

通用的风格规范

• 保持文档简洁，方便用户快速查看、导航到相关的代码文档（如模型指标、训练策略参考）。
• 保持与代码同步，改代码后同步更新文档、运行命令、单元测试，"Doc is the story of your code".
• 保证命令皆可执行，每次PR前请验证在非本地环境下新增的命令能否正常运行。
• 保证链接url有效，定期检查url是否失效。
• 图片上传到raw github server（拖拽即可），而非直接提交到代码仓内。
• 中英文档同步更新
• 英文文档语法错误检查，合入主仓前请使用grammarly等语法检查工具排查错误。
• 不断迭代，没有一次完美的文档，迭代优化，删繁就简。

主页Readme

内容纲要

主页应该清晰地给出以下信息：

语言切换栏：  EN|中文|繁体
章节导航栏: Introduction| Get Started| ... 

1. Introduction  介绍
   a. 定义和定位
   b. 主要特性
   c. Benchmark结果或效果展示 
       # 导航到Benchmark页面
   
2. Get Started 如何开始
   a. Installation 环境安装
   b. Quick Start 快速开始
      
3. Tutorials 文档教程
   # 层次，导航到各个教程页

4. APIs/ Model Support /Algorithm Support / Dataset Support
   # APIs，导航到readthedocs
   # Model Support, 简洁地列出已支持模型，并导航，详细内容在模型文件夹或是readthedocs上展示。
   # Algorithm Support，简洁地列出已支持算法, 并导航，详细讲解可在readthedocs上展示。
   # Dataset Support，简洁地列出已支持数据集，并导航，详细讲解可在readthedocs上展示。

5. What is new
   # 阶段性更新说明，导航到对应的更新代码页

6. Notes
   a. How to contribute
   b. Acknowledgement
   c. FAQs 

模型文档

每个模型的文档和配置文件都应存放在一个文件夹目录下，如configs/vit。

目录结构和命名规则

请见该章节 - File Structure and Naming

编写规范

请以ViT模型文档为统一模型，进行内容迁移。具体编写规范如下：

1. 模型Readme内容纲要与模板文档对齐。
2. 表格样式按照 https://github.com/mindspore-lab/mindcv/tree/main/configs#table-format
3. paper link 导航到paper abstract，而非pdf.
4. 引用：引用格式按照GB/T 7714，应在引用章节（References）声明论文，及其他内容出处（如introduction有参考到）。
5. 能用原生markdown表达则不用html标记语言，但不作强制要求，如居中等样式应用则用。若使用，可参考Google HTML/CSS代码风格指南。
6. Yaml 和 权重文件的url链接请同步更新，并使用绝对路径。

References

[1] https://github.com/google/styleguide/blob/gh-pages/docguide/best_practices.md