CANN/community文档写作规范

文档写作规范【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community概述本文档为CANN组织下的开源项目文档制定了统一的写作规范涵盖了内容、目录、元素和质量合规要求旨在确保所有文档风格一致、结构清晰、易于使用。开发者在进行CANN文档写作前请务必阅读并遵循本规范。欢迎随时提出改进建议。文档内容要求必选内容每个开源项目需要包含如下核心内容标题可以根据项目特点微调概述介绍项目的功能、架构与关键特性。编译安装提供完整的源码编译与构建指南。本地验证指导如何通过简单样例验证基础功能。贡献指南说明如何参与项目贡献。许可证声明项目遵循的开源许可协议。可选内容各开源项目可以根据实际情况补充如下内容包括但不限于样例使用指导examples的功能说明、编译执行步骤与结果示例等。参考文档相关产品文档、培训视频等资源的链接。定制开发指导基于项目源码进行二次开发的指南等。API参考开放的接口说明。目录结构规范总体原则【规则】单一项目的多个工具/组件文档应统一存放于docs目录下并按子目录分类管理。【规则】docs目录下区分zh中文与en英文子目录。【规则】若文档数量较少如单个算子可不区分zh/en目录采用文件后缀区分英文文件加_en后缀中文文件无后缀例如aclnnAbs.md与aclnnAbs_en.md。【规则】与代码强关联的文档如examples、算子说明直接归档在对应代码目录下。API文档目录规划【规则】每个API或每个类对应一个markdown文件单个项目规划保持统一。【规则】API文档必须提供目录索引文件如README.md或xx_list.md名字可自定义。API数量多时索引文件应置于API文件的上层目录。【规则】若API按框架、组件、语言等分类须通过子目录区分。目录结构示例# 示例1平铺结构文档较少 |-- xx_list.md |-- api1.md |-- api2.md |-- api3.md 示例2索引文件外提 |-- xx_list.md |-- context |--|-- api1.md |--|-- api2.md |--|-- api3.md |--|-- ... 示例3多语言API |-- c_api |--|-- c_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... |-- python_api |--|-- python_list.md |--|-- context |--|--|-- api1.md |--|--|-- api2.md |--|--|-- ... 示例4统一索引按功能特性分组 |-- api_list.md |--|-- feature1 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature2 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md |--|-- feature3 |--|--|-- api1.md |--|--|-- api2.md |--|--|-- api3.md内容元素规范文件命名对于新增文档请在对应的文件目录下新增 MarkDown 文档即以 .md 结尾的文件。【规则】文件名需要以英文小写命名。【规则】多个单词以下划线_连接。【规则】文件名不宜过长建议不超过50个字符。【规则】README文档中文命名为README.md英文命名为README_en.md。【规则】同一目录下不能出现重名文件。标题【规则】标题应简洁明了概括章节核心内容。【规则】操作类标题使用动宾结构例如“申请权限”同级别同类型标题结构保持一致。【规则】标题末尾不加标点避免使用特殊字符如“?”补充说明使用圆括号。【规则】标题与正文间空一行。【规则】标题使用#[空格][标题名]标题级别需逐级递增第一个标题应该是顶层标题。【规则】标题中不能手工添加序号例如 “## 1. 安装CANN”需要修改为 “## 安装CANN”。【规则】标题建议最多四级。【示例】# 一级标题 ## 二级标题 ### 三级标题 #### 四级标题字体样式【字体样式】斜体使用一个星号*表示斜体。*斜体文本*粗体使用两个星号**表示粗体。**粗体文本**粗斜体使用3个星号***表示粗斜体。***粗斜体文本***转义对特定内容使用转义符 \。\转义的标记符号\图片【规则】图片统一存放到文档同级目录下的figures文件夹中使用相对路径引用。【规则】请使用原创图片避免侵权。【规则】图文配合使用切忌图文分离。【规则】图片格式首选PNG次选JPG。【规则】 中/英文文档须分别使用对应语言的插图。【规则】截图应只保留核心内容关键信息可用红框或文字标注。【规则】确保图片清晰可辨。【图片插入格式】  # 示例  或 代码块【规则】确保代码的逻辑和语法正确。【规则】清晰区分输入与输出部分。【规则】关键步骤须有注释说明。【规则】文中行内代码和命令行使用1对反引号如行内代码。【规则】块级代码使用3个反引号并声明语言类型上下空一行。常见语言类型包括python、c、c、markdown、bash、ini、yaml、json、xml、html、java、javascript、php、sql、ruby等。【示例】行内代码printf() 函数块级代码#include stdio.h int main(void) { printf(Hello world\n); }#!/usr/bin/env python3 print(Hello, World!);输出Hello, World!列表【规则】有明显先后逻辑顺序情况请使用有序列表并列关系、多选一情况请使用无序列表。【规则】当项目列表是术语、短语时统一不加标点符号为完整句子时统一加句号混合情况下统一加句号。【规则】项目列表前几项以分号结尾最后一项以句号结尾的形式也可以接受。无序列表无序列表使用星号*、加号或是减号-作为列表标记这些标记后面要添加一个空格然后再填写内容。一个文件中的同一个无序列表建议使用同一个符号。* 第一项 * 第二项 * 第三项 第一项 第二项 第三项 - 第一项 - 第二项 - 第三项有序列表有序列表使用数字并加上.号来表示不支持使用字母例如a b c作为序号。1. 第一项 2. 第二项 3. 第三项嵌套列表列表嵌套只需在子列表中的选项前面添加两个或四个空格不要使用tab键即可。1. 第一项 - 第一项嵌套的第一个元素 - 第一项嵌套的第二个元素 2. 第二项 - 第二项嵌套的第一个元素 - 第二项嵌套的第二个元素 - 第一项 - 第一项嵌套的第一个元素 - 第一项嵌套的第二个元素 - 第二项 - 第二项嵌套的第一个元素 - 第二项嵌套的第二个元素注释符号文档中会出现以下注释符号代表提示的重要程度。说明提供辅助性提示或参考信息。 [!NOTE]说明 正文注意如未按此操作可能导致任务中断或结果异常可恢复。 [!CAUTION]注意 正文警告如不避免可能导致轻微或中度伤害。 [!WARNING]警告 正文写作要点请根据使用场景选择恰当的注释符号。注释块内可嵌套有序/无序列表但不建议表格和代码块。使用连续的符号以保证样式不中断。说明/注意等样式中内容应简洁过长可考虑迁移至正文或者分段处理。链接【规则】确保链接目标有效避免死链。【规则】引用文档时建议用书名号包裹并添加超链接。【示例】- 网站链接 AA的安装步骤请参考[《安装与部署》](https://www.aa.com)。 - 相对路径 [文档开发流水线门禁](https://link.gitcode.com/i/8930e5fe6a25e2a660ae492c4a81412b)锚点【规则】引用文档内标题、图片或表格时请使用锚点。锚点设置方法方法一将标题中大写字母转换为小写空格替换为中划线-并去除特殊符号。方法二添加a标签在a标签中自定义锚点ID。【示例】# 安装前准备 A* 这是CANN的安装前准备。 ... 参考[安装前准备](#安装前准备-a)章节。 **图1** CI 检查结果 a idfig11/a ... 参考图1[CI 检查结果](#fig11)。表格【规则】使用标准markdown表格语法若无特殊格式诉求不建议使用HTML表格。【规则】当表格内一列全部是术语、短语时统一不加标点符号为句子时统一加句号混合情况下统一加句号。【示例】表头1表头2单元格1单元格2单元格4单元格4【使用方法】 设置表格的对齐方式--: 设置内容和标题栏居右对齐。:-- 设置内容和标题栏居左对齐。:--: 设置内容和标题栏居中对齐。标点符号【规则】单位与数字之间不加空格比如50m10kg64Kbit/s。【规则】列表项标点使用保持一致。【规则】中文文档使用全角标点数字使用半角字符。【规则】感叹号仅用于可能引发严重人身或设备安全后果的警告。【规则】引用其他文档时添加书名号并建议增加引用文档的跳转链接。例如请参考《CANN软件安装指南》。贡献合规要求【规则】提交内容必须是与CANN特性相关内容。【规则】内容不能包含敏感信息、有强烈的种族歧视或性别歧视的内容。【规则】提交的内容必须是原创内容不得侵犯他人知识产权。【规则】提交的内容必须客观、真实不允许使用夸大宣传等词汇。文档贡献中不受欢迎的行为短时间内通过自动化工具提交大量的issue诸如拼写错误、语法错误、日期错误、语句不通顺等“无害错误”的修正。【免费下载链接】community本项目是CANN开源社区的核心管理仓库包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息项目地址: https://gitcode.com/cann/community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考