[PR #274] [CLOSED] docs: add comprehensive API reference documentation #337

New issue

Closed

opened 2026-10-26 21:16:24 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-26 21:16:24 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/deepseek-ai/DeepGEMM/pull/274
Author: @yurekami
Created: 1/3/2026
Status: ❌ Closed

Base: main ← Head: docs/add-api-reference

📝 Commits (1)

b8feb7d docs: add comprehensive API reference documentation

📊 Changes

1 file changed (+440 additions, -0 deletions)

View changed files

➕ docs/API_REFERENCE.md (+440 -0)

📄 Description

Summary

This PR adds comprehensive API reference documentation (docs/API_REFERENCE.md) for DeepGEMM, addressing the "Polish docs" item in the project roadmap.

Motivation

DeepGEMM has 45+ open issues, many of which stem from users not understanding the API correctly:

Layout confusion (NT vs NN vs TN vs TT)
Scaling factor format differences between SM90 and SM100
Alignment requirements for grouped GEMMs
Parameter shapes and types

This documentation provides a single, comprehensive reference for all functions.

Documentation Contents

Sections Included

Conventions and Notes - Layout naming, tensor dtypes, scaling factor formats
Configuration - set_num_sms, get_num_sms, set_tc_util, get_tc_util
Dense FP8 GEMM - All layout variants with shape tables
Dense BF16 GEMM - BF16 equivalents
M-Grouped GEMMs - MoE forward (contiguous and masked layouts)
K-Grouped GEMM - MoE backward/weight gradients
Attention Kernels - fp8_mqa_logits, fp8_paged_mqa_logits
Utilities - Alignment helpers, scaling factor transformation
SM90 vs SM100 Differences - Architecture-specific guidance
Common Pitfalls - Troubleshooting guide
End-to-End Examples - Complete working code
Environment Variables - All configuration options

Key Features

Complete function signatures with parameter tables
Tensor shape requirements for all layouts
Code examples that users can copy directly
Comparison table for SM90 vs SM100
Troubleshooting for common issues

Relation to Roadmap

This directly addresses the [ ] Polish docs item in README.md roadmap.

Test Plan

Verified markdown renders correctly on GitHub
Cross-referenced function names with deep_gemm/__init__.py
Validated parameter descriptions against test code
Checked examples compile conceptually (no GPU required)

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/deepseek-ai/DeepGEMM/pull/274 **Author:** [@yurekami](https://github.com/yurekami) **Created:** 1/3/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/add-api-reference` --- ### 📝 Commits (1) - [`b8feb7d`](https://github.com/deepseek-ai/DeepGEMM/commit/b8feb7d0a6aa20a53860c2b44dba0f1d18e04600) docs: add comprehensive API reference documentation ### 📊 Changes **1 file changed** (+440 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `docs/API_REFERENCE.md` (+440 -0) </details> ### 📄 Description ## Summary This PR adds comprehensive API reference documentation (`docs/API_REFERENCE.md`) for DeepGEMM, addressing the "Polish docs" item in the project roadmap. ## Motivation DeepGEMM has 45+ open issues, many of which stem from users not understanding the API correctly: - Layout confusion (NT vs NN vs TN vs TT) - Scaling factor format differences between SM90 and SM100 - Alignment requirements for grouped GEMMs - Parameter shapes and types This documentation provides a single, comprehensive reference for all functions. ## Documentation Contents ### Sections Included 1. **Conventions and Notes** - Layout naming, tensor dtypes, scaling factor formats 2. **Configuration** - `set_num_sms`, `get_num_sms`, `set_tc_util`, `get_tc_util` 3. **Dense FP8 GEMM** - All layout variants with shape tables 4. **Dense BF16 GEMM** - BF16 equivalents 5. **M-Grouped GEMMs** - MoE forward (contiguous and masked layouts) 6. **K-Grouped GEMM** - MoE backward/weight gradients 7. **Attention Kernels** - `fp8_mqa_logits`, `fp8_paged_mqa_logits` 8. **Utilities** - Alignment helpers, scaling factor transformation 9. **SM90 vs SM100 Differences** - Architecture-specific guidance 10. **Common Pitfalls** - Troubleshooting guide 11. **End-to-End Examples** - Complete working code 12. **Environment Variables** - All configuration options ### Key Features - Complete function signatures with parameter tables - Tensor shape requirements for all layouts - Code examples that users can copy directly - Comparison table for SM90 vs SM100 - Troubleshooting for common issues ## Relation to Roadmap This directly addresses the `[ ] Polish docs` item in README.md roadmap. ## Test Plan - [x] Verified markdown renders correctly on GitHub - [x] Cross-referenced function names with `deep_gemm/__init__.py` - [x] Validated parameter descriptions against test code - [x] Checked examples compile conceptually (no GPU required) 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-26 21:16:24 +00:00