文档贡献指南

欢迎您对本项目文档做出贡献，优质的文档对于项目成功至关重要。本指南将帮助您高效地提交符合规范的文档。

贡献范围

我们欢迎任何能提升文档质量的贡献，包括但不限于：

• 纠错与改进：修复错别字、语法错误、错误的代码示例、过时的信息或失效的链接。

• 澄清与优化：让描述更清晰易懂，优化语句结构，补充背景知识。

• 内容补充：为现有功能添加使用示例、API文档、常见问题解答（FAQ）、最佳实践或警告说明等。

• 新内容创作：为新增功能撰写全新的章节或教程，比如算子README、API介绍文档等，如有问题建议先创建Issue讨论。

• 本地化翻译：帮助我们翻译或校对其他语言的文档。

• 样式与导航：改进文档网站的布局、可读性和导航结构。

贡献流程

1. 准备工作

   • 确定任务：如有文档问题可新建Issues，建议标签类别[Documentation|文档反馈]，并提供详细描述。基于已有Issues列表，确定待解决的文档issue。
   • 认领任务：在对应的Issue下评论/assign @yourself ，表明您将处理它，避免重复劳动。

2. 文档修改

   • 选择分支：请从master或其他Tag分支下载源码到本地。
   • 遵循格式：
     • 本项目推荐使用Markdown格式。
     • 遵循项目既有的写作风格。
     • 图片等静态资源放入对应目录，例如图片一般在docs目录下figures文件夹，特殊情况可自行调整。
   • 谨慎增删：修改内容时，请尽量保持原有的行宽和换行约定。

3. 提交更改

   • 原子化提交：每个提交应专注于一个独立的修改。例如，“修复xx指南的拼写错误”和“更新API参考的示例代码”应分两次提交。

   • 撰写清晰的提交信息：

     简短说明（不超过50字符）
     
     如有必要，在此处进行更详细描述。说明修改的原因和内容，而不是具体改了什么（代码本身会展示）。
     关联的 Issue: #123
     

4. 发起Pull Request

   • 目标分支：请将PR合并到项目的目标分支。
   • 标题与描述：
     • PR标题：应清晰概括修改，例如：[Docs] 修复快速入门中的配置示例。
     • PR描述：详细说明您的更改内容、动机，并关联对应Issue（使用Closes #123或Fixes #456）。
   • 预览检查：请提前检查本地或在线浏览的文档效果，确保渲染符合预期。
   • 等待审查：维护者会进行审查，可能会提出修改建议。请及时跟进讨论。

写作规范

开发者进行项目文档写作前，请务必先阅读如下规范，如有问题欢迎您随时提出建议！

• 前提条件：请先学习CANN组织提供的统一写作规范，具体参见CANN文档写作规范。

  • 文档内容要求：介绍项目里必选和可选文档交付件。
  • 目录结构规范：介绍目录划分的原则，例如中、英文管理等。
  • 内容元素规范：介绍不同写作元素的规则，例如文件命名、标题、字体、图片、代码块、链接等。

• 注意事项：

  除了上述写作规则，还需注意以下事项：

  • 语气：使用友好、专业且中立的语气。面向新手，避免不必要的行话。
  • 术语：保持术语一致性（如统一使用“点击”而非“单击”）。请参考项目术语表（如有）。
  • 代码示例：
    • 确保所有代码示例可运行并经过测试。
    • 提供足够的上下文和解释。
    • 注明代码运行所需的环境或前提条件。
  • 标点与格式：
    • 中英文混排时，使用全角标点，标点符号必须符合中/英文语境。
    • 标题使用合适的层级（#、 ##、 ###）。
    • 使用列表和表格来组织复杂信息。
  • 链接：使用描述性链接文本，避免“点击这里”，确保链接资源真实可靠。
  • 图片：
    • 常用格式：推荐png格式，风格尽量与已有图片保持一致。
    • 分辨率与清晰度：需清晰且尺寸适中，避免模糊或过度压缩。
    • 文件大小：单张图片不建议超过10M。
  • 版权：所有引用的图片、文献等资源，请确保合规性。

获取帮助

如果您在贡献过程中有任何疑问：

1. 查阅现有文档：模板或规范有问题，请先查阅项目已有的指南、API文档或README等。
2. 发起讨论：您可以新建Issue或直接在相关Issue或PR中留言。

算子README模板

针对experimental新贡献算子，算子README是必备文档交付件，您可以参考本节提供的简单模板，也支持您基于本模板进行内容拓展。

• 文档格式：推荐Markdown文件格式，支持使用原生或Html语法，请确保所有语法须符合官方规范。
• 文档作用：阐述清楚算子功能、实现原理、参数规格以及算子调用方式等。
• 章节标题：优先使用模板章节名（如功能说明、参数说明等），标题层级为##，如有特殊情况层级请按序增加。支持章节自定义拓展，可选章节视情况呈现。
• 内容要求：每章内容写作目标、写作规范请参考下文详细描述，为方便理解，将以AddExample算子README为例。

产品支持情况

写作规范：推荐表格形式，罗列支持的产品型号，并打√，产品形态介绍请参见昇腾产品形态说明。

产品	是否支持
Atlas A3 训练系列产品/Atlas A3 推理系列产品	√
Atlas A2 训练系列产品/Atlas A2 推理系列产品	√

功能说明

• 算子功能：完成张量加法计算。
• 计算公式：

  $$y=x1+x2$$

参数说明

参数名	输入/输出/属性	描述	数据类型	数据格式
x1	输入	表示add_example计算的第一个张量，即公式中x1。	FLOAT、FLOAT16、INT32	ND
x2	输入	表示add_example计算的第二个张量，即公式中x2。	数据类型与x1保持一致	ND
y	输出	表示add_example计算结果张量，即公式中y。	FLOAT、FLOAT16、INT32	ND

约束说明（可选）

无

调用说明

调用方式	调用样例	说明
aclnn调用	test_aclnn_add_example	参见算子调用完成算子编译和验证。
图模式调用	test_geir_add_example

参考资源（可选）

无