[Docs] Add Sphinx documentation website with GitHub Actions deployment

[sunway513]

Summary

• Add Sphinx-based documentation website with automated GitHub Actions deployment to GitHub Pages
• Include API reference docs for attention, GEMM, and operator modules
• Add tutorials: basic usage guide and "How to Add a New Operator" guide
• Include installation guide, quickstart, and deployment documentation

Files Added

• .github/workflows/docs.yml - GitHub Actions workflow for building and deploying Sphinx docs
• docs/conf.py, docs/index.rst, docs/Makefile, docs/requirements.txt - Sphinx build configuration
• docs/api/ - API reference documentation (attention, gemm, operators)
• docs/tutorials/ - User tutorials (basic usage, adding new operators)
• docs/installation.rst, docs/quickstart.rst - Getting started guides

Test plan

• Verify Sphinx builds successfully: cd docs && pip install -r requirements.txt && make html
• Verify GitHub Actions workflow triggers on push to docs-website branch
• Review generated HTML output for correctness

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a Sphinx-based documentation site for AITER (API reference + tutorials) and introduces GitHub Actions automation for building and deploying the docs to GitHub Pages, alongside repo-size hygiene updates (gitignore + test-data download stub + cleanup plan).

Changes:

• Introduce a Sphinx docs site scaffold (docs/), including API reference and tutorials.
• Add a GitHub Actions workflow to build docs and deploy to GitHub Pages.
• Add repo cleanup guidance and guardrails for large-file/test-data management (.gitignore, download script, cleanup plan).

Reviewed changes

Copilot reviewed 18 out of 21 changed files in this pull request and generated 24 comments.

Show a summary per file

File	Description
.github/workflows/docs.yml	CI job to build Sphinx docs and deploy HTML to GitHub Pages.
.gitignore	Adds patterns to prevent committing large test artifacts/data.
REPO_CLEANUP_PLAN.md	Documents planned repo history cleanup and migration steps.
scripts/download_test_data.sh	Placeholder script for externally-hosted test data downloads.
docs/conf.py	Sphinx configuration (extensions, theme, intersphinx).
docs/index.rst	Docs landing page + top-level navigation/toctrees.
docs/installation.rst	Installation guide and verification steps.
docs/quickstart.rst	“5 minute” quickstart examples across key features.
docs/requirements.txt	Python dependencies for building docs.
docs/Makefile	Sphinx build targets (html, livehtml, clean-all).
docs/README.md	Local build instructions and docs contribution guidance.
docs/DEPLOYMENT.md	Intended deployment process and operational notes.
docs/DOCUMENTATION_AUDIT_REPORT.md	Captures an accuracy audit and outstanding issues.
docs/api/attention.rst	Attention API reference via autodoc + narrative.
docs/api/gemm.rst	GEMM API reference via autodoc + narrative.
docs/api/operators.rst	Operator API reference via autodoc + narrative.
docs/tutorials/index.rst	Tutorials index + navigation/toctrees.
docs/tutorials/basic_usage.rst	Basic usage tutorial with code examples.
docs/tutorials/add_new_op.rst	Tutorial describing how to add a new operator.
docs/_static/.gitkeep	Keeps static asset directory tracked.
docs/_templates/.gitkeep	Keeps templates directory tracked.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The quickstart's KV-cache example calls aiter.flash_attn_with_kvcache(query, kv_cache, page_table, block_size=...), but flash_attn_with_kvcache is not part of the public aiter namespace and the implementation that exists expects separate k_cache/v_cache (and uses block_table naming). As written, this snippet will raise AttributeError/TypeError; please update it to match the actual exported API or document the correct module path + signature.

Suggested change

	# Query with variable lengths per batch
	query = torch.randn(5, 2048, 16, 64, device='cuda', dtype=torch.float16)
	# Page table configuration (see tutorials for details)
	page_table = torch.tensor([[0, 1, 2], [3, 4, 5]], device='cuda', dtype=torch.int32)
	# KV cache in paged format
	kv_cache = torch.randn(6, 16, 128, 64, device='cuda', dtype=torch.float16)
	# Variable-length attention with page tables
	output = aiter.flash_attn_with_kvcache(
	query, kv_cache, page_table,
	from aiter.kvcache import flash_attn_with_kvcache
	# Query with variable lengths per batch
	query = torch.randn(5, 2048, 16, 64, device='cuda', dtype=torch.float16)
	# Block table configuration (see tutorials for details)
	block_table = torch.tensor([[0, 1, 2], [3, 4, 5]], device='cuda', dtype=torch.int32)
	# K/V caches in paged format
	k_cache = torch.randn(6, 16, 128, 64, device='cuda', dtype=torch.float16)
	v_cache = torch.randn(6, 16, 128, 64, device='cuda', dtype=torch.float16)
	# Variable-length attention with page tables
	output = flash_attn_with_kvcache(
	query, k_cache, v_cache, block_table,

[Copilot]

aiter.rmsnorm is an in-place style API that takes an out tensor first (rmsnorm(out, input, weight, epsilon)), but this doc section describes it as a functional API returning a new tensor and uses eps naming. Please update the description/examples to match the real signature (or document the correct functional wrapper if users shouldn't call this low-level op).

[Copilot]

aiter.gelu / aiter.swiglu are referenced here, but the exported activation APIs are gelu_and_mul / gelu_tanh_and_mul (and there is no top-level swiglu). These autodoc directives will fail and the examples won't run; please update this page to the actual available activation functions (or add wrappers matching the documented names).

[Copilot]

This RoPE section documents aiter.apply_rotary_pos_emb and aiter.precompute_rope_embeddings, but those symbols don't exist in the aiter package (the exported APIs are rope_* functions). Sphinx autodoc will fail and the example code will error; please replace these with the real RoPE API entry points or add wrappers with the documented names.

[Copilot]

The deployment step uses peaceiris/actions-gh-pages@v3, which is an old major version and may be pinned to deprecated Node runtimes. Consider upgrading to the latest supported major version and pinning the action by full commit SHA to reduce supply-chain risk.

[Copilot]

The MoE example uses aiter.fmoe(...) as if it returns an output tensor and accepts (x, w1, w2, router_logits, topk=..., renormalize=...), but the exported aiter.fmoe is a low-level in-place op that requires an out tensor plus precomputed sorted routing metadata. This example won't run; consider either switching to the high-level MoE API (if any) or expanding the example to show how to compute topk_weights/topk_ids and the required sorted indices before calling the kernel.

Suggested change

	# Router logits and expert selection
	router_logits = torch.randn(num_tokens, num_experts, device='cuda', dtype=torch.float16)
	# Fused MOE operation (gate + up projection + down projection)
	output = aiter.fmoe(
	x, w1, w2, router_logits,
	topk=top_k,
	renormalize=True
	)
	# Router logits
	router_logits = torch.randn(num_tokens, num_experts, device='cuda', dtype=torch.float16)
	# Compute routing probabilities and top-k experts per token
	router_probs = torch.softmax(router_logits, dim=-1)
	topk_weights, topk_ids = torch.topk(router_probs, k=top_k, dim=-1)
	# Flatten and sort by expert id to form grouped GEMM batches
	flat_expert_ids = topk_ids.reshape(-1) # [num_tokens * top_k]
	flat_token_ids = torch.arange(num_tokens, device=x.device).repeat_interleave(top_k)
	sorted_expert_ids, sort_indices = torch.sort(flat_expert_ids, stable=True)
	sorted_token_ids = flat_token_ids[sort_indices]
	# Allocate output buffer for the low-level fused MoE kernel
	output = torch.empty_like(x)
	# Low-level fused MoE operation (gate + up projection + down projection).
	# NOTE: aiter.fmoe is an in-place kernel that writes into `output` and expects
	# precomputed routing metadata. Refer to the AITER documentation for the exact
	# argument order. A typical call structure looks like:
	#
	# aiter.fmoe(
	# x,
	# w1,
	# w2,
	# topk_weights,
	# topk_ids,
	# sorted_token_ids,
	# sorted_expert_ids,
	# out=output,
	# )

[Copilot]

These attention variants (grouped_query_attention, multi_query_attention, variable_length_attention) are documented but don't exist anywhere in the aiter Python package. Sphinx autodoc will fail and users will hit AttributeError; either remove these sections or rename them to the actual available APIs (e.g. flash_attn_varlen_func, paged-attention helpers, etc.).

[Copilot]

aiter.layernorm is referenced for autodoc, but there is no layernorm function exported at the top level (only layernorm2d_* variants exist). This will break Sphinx autodoc and mislead users; please update the docs to reference the actual exported LayerNorm API or add a real layernorm wrapper in the library.

Suggested change

.. autofunction:: aiter.layernorm

[Copilot]

The tutorial suggests importing my_custom_op_impl from aiter._C, but this repository doesn't define an aiter._C extension module. Please update the tutorial to match AITER's actual JIT/compile_ops workflow for building and loading custom kernels, or clearly state that the snippet is illustrative only (and not expected to run as-is).

Suggested change

	# Import the C++ extension
	from aiter._C import my_custom_op_impl
	# Input validation
	assert input.is_cuda, "Input must be on CUDA device"
	assert input.dtype in [torch.float16, torch.bfloat16], \
	"Only FP16/BF16 supported"
	# Call C++ implementation
	return my_custom_op_impl(input, weight, bias, activation)
	# NOTE: This is illustrative. The actual implementation of
	# `my_custom_op_impl` depends on how you build and load your
	# custom kernel using AITER's JIT/`compile_ops` workflow
	# described in Step 3: Create Python Bindings.
	# Input validation
	assert input.is_cuda, "Input must be on CUDA device"
	assert input.dtype in [torch.float16, torch.bfloat16], \
	"Only FP16/BF16 supported"
	# Call into the compiled implementation (to be provided by your
	# bindings; see Step 3 of this tutorial for details).
	raise NotImplementedError(
	"my_custom_op_impl is provided by the custom kernel bindings; "
	"see 'Step 3: Create Python Bindings' for how to wire this up."
	)

[Copilot]

This deployment guide recommends using the third-party GitHub Action easingthemes/ssh-deploy@v4 with a private SSH key passed via SSH_PRIVATE_KEY, but pins it only to the mutable v4 tag. If that action or its supply chain is compromised, an attacker could use your deployment key to modify content on doc.aiter.amd.com or pivot further into your infrastructure. To mitigate this, pin the action to a specific commit SHA (and update it deliberately over time) or replace it with a first-party/organization-maintained deployment mechanism that you control more directly.

[sunway513]

Hi @valarLip @gyohuangxin — friendly ping for review on this documentation website PR. This adds Sphinx-based docs with GitHub Actions auto-deployment to GitHub Pages, covering API reference and tutorials. Would appreciate your review when you get a chance. Thanks!

[gyohuangxin]

docs.yml should only trigger when docs-related files are modified. Please add path filters:

on:
  push:
    branches:
      - main
      - docs-website
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  pull_request:
    branches:
      - main
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

This avoids unnecessary CI runs when non-doc files are changed.

[gyohuangxin]

@sunway513 Could you also fix code style issues listed here: https://github.com/ROCm/aiter/actions/runs/22835735370/job/66231715645?pr=2167