external-gitcode-ascend-ascendc-operator-doc-gen

AscendC Operator Interface Documentation Generation

Extract interface information from operator source code and generate PyTorch official documentation style Chinese API interface documentation.

Prerequisites: Compilation and testing pass (Phase 3 completed), and the following files are all ready:

• csrc/register.cpp — Contains the m.def registered Python call schema
• csrc/ops.h — Contains the C++ function declaration
• csrc/ops/<op_name>/design.md — Contains the algorithm description, parameter descriptions, dtype support, and constraints
• csrc/ops/<op_name>/op_host/<op_name>.cpp — Contains TORCH_CHECK constraints and the actual parameter handling logic
• tests/test_<op_name>.py — Contains runnable call examples

Workflow

信息提取 → 文档结构组装 → 文件生成 → 聊天界面展示

---

Phase 1: Information Extraction

Extract all information required for the interface documentation from the following source files.MUST Read these files one by one; do not skip any.

1.1 From csrc/register.cpp Extract the Python call signature

Find the m.def("<op_name>(...) line and extract the complete schema string.

Extraction contents：

• Function name
• Parameter list (including types and default values)
• Return type

Example：

m.def("acosh(Tensor self) -> Tensor");

→ Signature: torch.ops.npu.acosh(self) → Tensor

Schema type to Python type mapping：

Schema type	Python documentation type	Example
Tensor	Tensor	Required tensor parameter
Tensor?	Tensor, optional	Optional tensor parameter
Tensor(a!)	Tensor	In-place modified tensor
int	int	Integer parameter
int?	int, optional	Optional integer parameter
int[]	list[int]	Integer list
int[3]	list[int]	Fixed-length integer list
float	float	Floating-point parameter
bool	bool	Boolean parameter
str?	str, optional	Optional string parameter

1.2 From csrc/ops.h Extract the C++ function declaration

Find the complete C++ signature of the corresponding function in namespace ascend_kernel .

Extraction contents：

• Return type (at::Tensor、void , etc.)
• Parameter types and parameter names
• Whether parameters are const references / optional

1.3 From design.md Extract algorithm and design information

Extraction contents：

Extraction item	Design document section	Documentation purpose
Algorithm description / mathematical formula	Computation logic design	Function description paragraph
Parameter semantic description	Operator interface definition	Parameter description paragraph
Supported data types	Operator interface definition	Supported data types paragraph
Input/output shape constraints	Tiling strategy / operator interface definition	Shape paragraph
Valid input range / constraints	Notes / interface definition	Constraints paragraph

1.4 From op_host/<op_name>.cpp Extract runtime constraints

Search all TORCH_CHECK(...) statements and extract:

TORCH_CHECK content	Documentation purpose
Dimension check (dim() == N）	Shape constraints
dtype check (scalar_type() == kHalf）	Supported data types
Value range check (numeric range limits)	Constraints
Parameter mutual exclusion/dependency relationships	Constraints / Parameter description

1.5 From tests/test_<op_name>.py extract usage examples

Find the most concise and complete call example (prefer code in run_simple_test or test_basic ), extract:

• Input tensor construction method
• Operator call statement (torch.ops.npu.<op_name>(...)）
• Output handling method

---

Stage 2: Document structure assembly

Assemble the document content according to the following fixed structure . The format strictly follows the PyTorch official documentation (such as torch.nn.RMSNorm、torch.abs），The document body uses Chinese。

Document template

# torch.ops.npu.<op_name>

torch.ops.npu.<op_name>(, , ..., ) →

<功能描述：1-3句中文说明算子做什么。如果有数学公式，用 LaTeX 行内公式展示。>

<如有数学公式，用独立公式块展示：>

$$
<公式>
$$

## 参数说明

- **<param1>** (*<type>*) – <中文描述>
- **<param2>** (*<type>*) – <中文描述>
- **<param3>** (*<type>, optional*) – <中文描述>。默认值: `<默认值>`

## 支持的数据类型

`torch.float16`, `torch.bfloat16`, `torch.float32`

## Shape

- **输入**: <shape描述，使用数学符号如 (N, *), (S, N, D) 等>
- **输出**: <shape描述>

<如有额外 shape 规则，以列表形式补充>

## 约束条件

- <约束条件1>
- <约束条件2>

## 使用示例

```python
>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> <构造输入>
>>> <调用算子>
>>> <展示输出>

Return value

<return type> – <Chinese return value description>

### 各段落详细规范

#### 标题签名

- 格式：`torch.ops.npu.<op_name>(<参数列表>) → <返回类型>`
- 参数列表从 `register.cpp` 的 schema 提取，仅保留参数名（不带类型）
- 有默认值的参数写为 `<name>=<default>`
- 返回类型：`Tensor`、`tuple[Tensor, ...]`、`None`（对应 C++ `void`）

#### 功能描述

- 使用中文撰写
- 第一句话概括算子功能
- 如有数学公式，用 LaTeX 展示
- 如有多种工作模式（由参数控制），分别说明

#### 参数说明

- 每个参数一行，格式：`- **<name>** (*<type>*) – <中文描述>`
- 可选参数标注 `optional`：`- **<name>** (*<type>, optional*) – <中文描述>。默认值: \`<value>\``
- 参数描述应包含：语义说明、shape 要求（如适用）、有效值范围（如适用）
- Tensor 参数说明 shape 格式，如 "形状: `(S, N, D)`"
- 布尔/枚举参数说明各取值的含义

#### 支持的数据类型

- 列出算子支持的所有 PyTorch dtype
- 格式：`` `torch.float16`, `torch.bfloat16`, `torch.float32` ``
- 从 op_host 的 TORCH_CHECK 和 design.md 交叉验证

#### Shape

- 使用中文标签（**输入**、**输出**）
- 描述输入输出 tensor 的 shape 语义
- 使用大写字母表示各维度含义，如 `(N, C, H, W)` — N: 批大小, C: 通道数, ...
- 如果 shape 随参数变化，分情况说明

#### 约束条件

- 使用中文撰写
- 列出所有 TORCH_CHECK 中检查的约束条件
- 列出 design.md 中提到的有效输入范围
- 如果存在参数之间的互斥/依赖关系，明确说明

#### 使用示例

- 提供可直接在 NPU 上运行的完整代码片段
- 包含 `import` 语句
- 使用 `>>>` 前缀（doctest 风格）
- 输入数据使用小尺寸（便于展示）
- 展示至少 1 个典型用例
- 如果有多种使用模式，各展示 1 个

#### 返回值

- 使用中文描述
- 格式：`*<type>* – <中文描述>`
- 说明返回 tensor 的 shape 和 dtype（如与输入一致则注明"与输入 dtype 一致"）
- 如返回多个值（tuple），逐一说明

---

## 阶段 3: 文件生成

将组装好的文档写入：

ascend-kernel/csrc/ops/<op_name>/README.md

**文件写入规则**：
- 如果 README.md 已存在，**覆盖**旧内容
- 使用 UTF-8 编码
- 数学公式使用标准 LaTeX 语法（`$...$` 行内，`$$...$$` 块级）

---

## 阶段 4: 在交互界面展示文档（MANDATORY）

文件生成后，**MUST** 将完整的 README.md 内容直接输出到聊天界面中。

**展示格式**：

Interface documentation generated

File path: ascend-kernel/csrc/ops/<op_name>/README.md

<complete README.md content>

**要求**：
1. 展示完整文档内容，不要截断
2. 展示文件路径供用户查看
3. 如果某个段落因信息不足无法填写，用 `[TODO: ...]` 标注并提醒用户补充

---

## 完整示例

以下是一个假设的 `acosh` 算子的接口文档示例，展示最终生成效果：

> **说明**：此示例仅用于展示文档格式，实际生成时所有信息均从源代码提取。

````markdown
# torch.ops.npu.acosh

torch.ops.npu.acosh(self) → Tensor

逐元素计算输入张量的反双曲余弦值。

$$
\text{out}_i = \cosh^{-1}(\text{input}_i) = \ln(\text{input}_i + \sqrt{\text{input}_i^2 - 1})
$$

## 参数说明

- **self** (*Tensor*) – 输入张量，元素值必须 $\geq 1$。支持任意形状。

## 支持的数据类型

`torch.float16`, `torch.float32`

## Shape

- **输入**: $(*)$，支持任意形状
- **输出**: $(*)$，与输入形状相同

## 约束条件

- 仅支持 `float16` 和 `float32` 数据类型
- 输入张量的所有元素必须 $\geq 1$，否则结果为 `NaN`

## 使用示例

```python
>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> x = torch.tensor([1.0, 2.0, 3.0, 10.0], dtype=torch.float32, device="npu:0")
>>> output = torch.ops.npu.acosh(x)
>>> output
tensor([0.0000, 1.3170, 1.7627, 2.9932], device='npu:0')

Return value

Tensor – Inverse hyperbolic cosine computation result, shape same as input, dtype consistent with input.

---

## 检查清单

文档生成后按以下清单逐项验证：

- [ ] **签名一致性**: `torch.ops.npu.<op_name>(...)` 的参数列表与 `register.cpp` 的 `m.def` 完全一致
- [ ] **参数完整性**: 每个参数都有类型标注和中文语义描述
- [ ] **默认值正确**: 有默认值的参数在签名和参数说明中都标注了默认值
- [ ] **dtype 准确**: 支持的数据类型与 op_host TORCH_CHECK 和 design.md 一致
- [ ] **Shape 清晰**: 输入输出 shape 描述使用了有语义的维度符号
- [ ] **约束完整**: 所有 TORCH_CHECK 的检查条件都已体现
- [ ] **示例可运行**: 使用示例中的代码是从 test 文件中提炼的可执行代码
- [ ] **返回值明确**: 返回类型、shape、dtype 都已说明
- [ ] **中文表述**: 功能描述、参数说明、约束条件、返回值均使用中文
- [ ] **文件已生成**: README.md 已写入 `csrc/ops/<op_name>/README.md`
- [ ] **已在聊天界面展示完整文档内容**

## 反模式清单

- **NEVER** 编造参数或 dtype 信息，所有信息必须从源代码提取
- **NEVER** 跳过 TORCH_CHECK 约束的提取
- **NEVER** 使用与 register.cpp schema 不一致的参数名或类型
- **NEVER** 省略使用示例段落
- **NEVER** 仅输出文件路径而不在聊天界面展示完整文档内容
- **NEVER** 修改算子源代码，本 skill 是只读文档生成
- **NEVER** 使用英文撰写文档正文（标题签名、代码、数学公式除外）

## 可读取文件范围

| 文件 | 读取内容 |
|------|---------|
| `csrc/register.cpp` | Python 调用 schema（`m.def`） |
| `csrc/ops.h` | C++ 函数声明 |
| `csrc/ops/<op_name>/design.md` | 算法描述、参数说明、dtype、约束 |
| `csrc/ops/<op_name>/op_host/<op_name>.cpp` | TORCH_CHECK 约束、参数处理逻辑 |
| `tests/test_<op_name>.py` | 使用示例 |