docs: comprehensive documentation overhaul

.github/changelog-config.json

@@ -0,0 +1,44 @@
+{
+  "categories": [
+    {
+      "title": "## New Features",
+      "labels": ["feature", "enhancement"]
+    },
+    {
+      "title": "## Performance",
+      "labels": ["performance", "optimization"]
+    },
+    {
+      "title": "## Bug Fixes",
+      "labels": ["bug", "fix"]
+    },
+    {
+      "title": "## Refactoring",
+      "labels": ["refactor", "cleanup"]
+    },
+    {
+      "title": "## Infrastructure",
+      "labels": ["ci", "infrastructure", "build"]
+    }
+  ],
+  "sort": {
+    "order": "ASC",
+    "on_property": "mergedAt"
+  },
+  "template": "#{{CHANGELOG}}\n\n**Full Changelog**: https://github.com/ROCm/aiter/compare/{{FROM_TAG}}...{{TO_TAG}}",
+  "pr_template": "- {{TITLE}} (#{{NUMBER}})",
+  "empty_template": "No changes.",
+  "label_extractor": [
+    {
+      "pattern": "^(feat|feature|add|Add|new)",
+      "target": "$1",
+      "on_property": "title",
+      "method": "match",
+      "flags": "i"
+    }
+  ],
+  "max_tags_to_fetch": 200,
+  "max_pull_requests": 1000,
+  "max_back_track_time_days": 90,
+  "base_branches": ["main"]
+}

.github/workflows/aiter-release.yaml

@@ -35,26 +35,28 @@ on:
       docker_username:
         description: 'Docker username for docker login'
         required: true
-        default: 'rocmshard'
+        default: 'rocmshared'
       gpu_archs:
         description: 'GPU architectures (e.g. gfx942;gfx950)'
         required: false
         default: 'gfx942;gfx950'
+      rocm_version:
+        description: 'ROCm version label for wheel (e.g. 7.2.1). Auto-detected from container if empty.'
+        required: false
+        default: ''
       runner:
         description: 'Select build host'
         required: true
-        default: 'aiter-k8s-build'
+        default: 'aiter-1gpu-runner'
         type: choice
         options:
-          - build-only-aiter
-          - aiter-mi300-1gpu
-          - aiter-mi325-1gpu
-          - linux-aiter-mi355-1
           - aiter-1gpu-runner
+          - build-only-aiter
+          - linux-aiter-mi35x-1
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event.inputs.rocm_version || 'default' }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/v') }}
 
 jobs:
   build_whl_package:
@@ -120,6 +122,48 @@ jobs:
           --name aiter_build_${{ matrix.python_version }} \
           ${{ env.BUILD_DOCKER_IMAGE }}
 
+      - name: Detect ROCm version
+        if: ${{ matrix.build_enabled }}
+        id: rocm_ver
+        run: |
+          set -e
+          INPUT_VER="${{ github.event.inputs.rocm_version }}"
+          if [ -n "$INPUT_VER" ]; then
+            echo "Using user-provided ROCm version: $INPUT_VER"
+            echo "rocm_version=$INPUT_VER" >> "$GITHUB_OUTPUT"
+          else
+            DETECTED=$(docker exec aiter_build_${{ matrix.python_version }} \
+              bash -c 'cat /opt/rocm/.info/version 2>/dev/null || echo ""' | tr -d '[:space:]')
+            if [ -n "$DETECTED" ]; then
+              DETECTED=$(echo "$DETECTED" | cut -d'-' -f1)
+              echo "Auto-detected ROCm version: $DETECTED"
+              echo "rocm_version=$DETECTED" >> "$GITHUB_OUTPUT"
+            else
+              echo "WARNING: Could not detect ROCm version, wheel will have no ROCm suffix"
+              echo "rocm_version=" >> "$GITHUB_OUTPUT"
+            fi
+          fi
+
+      - name: Determine wheel version
+        if: ${{ matrix.build_enabled }}
+        id: whl_ver
+        run: |
+          set -e
+          ROCM_VER="${{ steps.rocm_ver.outputs.rocm_version }}"
+          BASE_VER=$(docker exec -w /workspace aiter_build_${{ matrix.python_version }} \
+            python3 -c "from setuptools_scm import get_version; print(get_version())" 2>/dev/null || true)
+          if [ -z "$BASE_VER" ]; then
+            BASE_VER=$(git describe --tags --match 'v*' 2>/dev/null | sed 's/^v//' || echo "0.1.0")
+          fi
+          if [ -n "$ROCM_VER" ]; then
+            FULL_VER="${BASE_VER}+rocm${ROCM_VER}"
+          else
+            FULL_VER="${BASE_VER}"
+          fi
+          echo "Wheel version: $FULL_VER (base=$BASE_VER, rocm=$ROCM_VER)"
+          echo "full_version=$FULL_VER" >> "$GITHUB_OUTPUT"
+          echo "rocm_suffix=rocm${ROCM_VER}" >> "$GITHUB_OUTPUT"
+
       - name: Install Dependencies
         if: ${{ matrix.build_enabled }}
         run: |
@@ -129,7 +173,16 @@ jobs:
           -w /workspace \
           aiter_build_${{ matrix.python_version }} \
           pip install --timeout=60 --retries=10 -r requirements.txt
-
+
+      - name: Pin setuptools_scm
+        if: ${{ matrix.build_enabled }}
+        run: |
+          set -e
+          docker exec \
+          -w /workspace \
+          aiter_build_${{ matrix.python_version }} \
+          pip install --timeout=60 --retries=10 "setuptools_scm<10"
+
       - name: Install ninja
         if: ${{ matrix.build_enabled }}
         run: |
@@ -140,21 +193,22 @@ jobs:
           aiter_build_${{ matrix.python_version }} \
           pip install --timeout=60 --retries=10 ninja
 
-      - name: Build Aiter
+      - name: Build Aiter with precompiled kernels
         if: ${{ matrix.build_enabled }}
         run: |
           set -e
-          echo "Building aiter whl packages for Python ${{ matrix.python_version }}..."
+          FULL_VER="${{ steps.whl_ver.outputs.full_version }}"
+          echo "Building aiter whl version=${FULL_VER} with PREBUILD_KERNELS=1 for Python ${{ matrix.python_version }}..."
           docker exec \
           -w /workspace \
           aiter_build_${{ matrix.python_version }} \
-          bash -c 'PREBUILD_KERNELS=1 GPU_ARCHS="${{ env.GPU_ARCHS }}" python3 setup.py bdist_wheel && ls dist/*.whl'
+          bash -c "SETUPTOOLS_SCM_PRETEND_VERSION='${FULL_VER}' PREBUILD_KERNELS=1 GPU_ARCHS='${{ env.GPU_ARCHS }}' python3 setup.py bdist_wheel && ls -lh dist/*.whl"
 
       - name: Upload whl file as artifact
         if: ${{ matrix.build_enabled }}
         uses: actions/upload-artifact@v4
         with:
-          name: aiter-whl-packages-py${{ matrix.python_version }}-${{ github.run_id }}-${{ github.run_attempt }}
+          name: aiter-whl-py${{ matrix.python_version }}-${{ steps.whl_ver.outputs.rocm_suffix }}-${{ github.run_id }}
           path: dist/*.whl
 
       - name: Cleanup container

.github/workflows/docs.yml

@@ -8,6 +8,8 @@ on:
     paths:
       - 'docs/**'
       - '.github/workflows/docs.yml'
+  release:
+    types: [published]
   pull_request:
     branches:
       - main
@@ -47,7 +49,12 @@ jobs:
       - name: Build Sphinx documentation
         run: |
           cd docs
-          make html
+          sphinx-build -W --keep-going -b html . _build/html
+
+      - name: Check for broken links
+        run: |
+          cd docs
+          sphinx-build -b linkcheck . _build/linkcheck || true  # Non-blocking, report only
 
       - name: Upload documentation artifacts
         uses: actions/upload-artifact@v4
@@ -59,7 +66,9 @@ jobs:
   deploy-docs:
     needs: build-docs
     runs-on: ubuntu-latest
-    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs-website')
+    if: >
+      (github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/docs-website' || startsWith(github.ref, 'refs/tags/v')))
+      || github.event_name == 'release'
 
     permissions:
       contents: write  # For GitHub Pages deployment
@@ -76,27 +85,4 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./html
-          cname: doc.aiter.amd.com  # Custom domain
           commit_message: 'docs: deploy documentation'
-
-  # Alternative: Deploy to AMD servers via SSH
-  # deploy-to-amd:
-  #   needs: build-docs
-  #   runs-on: ubuntu-latest
-  #   if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-  #
-  #   steps:
-  #     - name: Download documentation artifacts
-  #       uses: actions/download-artifact@v4
-  #       with:
-  #         name: documentation
-  #         path: ./html
-  #
-  #     - name: Deploy to AMD doc server
-  #       uses: easingthemes/ssh-deploy@v4
-  #       with:
-  #         SSH_PRIVATE_KEY: ${{ secrets.AMD_DOC_SERVER_KEY }}
-  #         REMOTE_HOST: doc.aiter.amd.com
-  #         REMOTE_USER: deploy
-  #         SOURCE: "html/"
-  #         TARGET: "/var/www/doc.aiter.amd.com/html"

.github/workflows/release-notify.yml

@@ -0,0 +1,86 @@
+name: Release Notification
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  notify-slack:
+    runs-on: ubuntu-latest
+    if: "!github.event.release.prerelease"
+    steps:
+      - name: Notify Slack
+        uses: slackapi/slack-github-action@v2.0.0
+        with:
+          webhook-url: ${{ secrets.AITER_RELEASE_SLACK_WEBHOOK }}
+          payload: |
+            {
+              "text": "AITER ${{ github.event.release.tag_name }} released",
+              "blocks": [
+                {
+                  "type": "header",
+                  "text": {
+                    "type": "plain_text",
+                    "text": "AITER ${{ github.event.release.tag_name }} Released"
+                  }
+                },
+                {
+                  "type": "section",
+                  "text": {
+                    "type": "mrkdwn",
+                    "text": "${{ github.event.release.body && '```' || 'See release page for details.' }}"
+                  }
+                },
+                {
+                  "type": "actions",
+                  "elements": [
+                    {
+                      "type": "button",
+                      "text": {
+                        "type": "plain_text",
+                        "text": "View Release"
+                      },
+                      "url": "${{ github.event.release.html_url }}"
+                    }
+                  ]
+                }
+              ]
+            }
+
+  notify-downstream:
+    runs-on: ubuntu-latest
+    if: "!github.event.release.prerelease"
+    strategy:
+      matrix:
+        repo: ['ROCm/ATOM']
+    steps:
+      - name: Create tracking issue
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.CROSS_REPO_TOKEN }}
+          script: |
+            const tag = '${{ github.event.release.tag_name }}';
+            const url = '${{ github.event.release.html_url }}';
+            const repo = '${{ matrix.repo }}'.split('/');
+
+            await github.rest.issues.create({
+              owner: repo[0],
+              repo: repo[1],
+              title: `AITER ${tag} available — dependency update`,
+              body: [
+                `A new AITER release is available: [${tag}](${url})`,
+                '',
+                '### Action Items',
+                '- [ ] Update AITER dependency to ' + tag,
+                '- [ ] Run integration tests',
+                '- [ ] Verify accuracy baselines',
+                '',
+                '### Install',
+                '```bash',
+                'pip install amd-aiter --find-links ' + url,
+                '```',
+                '',
+                'Auto-generated by AITER release workflow.'
+              ].join('\n'),
+              labels: ['dependency-update']
+            });

docs/advanced/triton_kernels.rst

@@ -0,0 +1,41 @@
+Triton Kernels
+==============
+
+AITER uses `Triton <https://triton-lang.org/>`_ as one of its backend
+implementations for GPU kernels. Triton kernels are written in Python and
+compiled to GPU machine code at runtime.
+
+Source Locations
+-----------------
+
+Triton kernel sources are located in two directories:
+
+- ``aiter/ops/triton/`` -- Triton-based operator implementations that are
+  called from the main ops API.
+- ``aiter/_triton_kernels/`` -- Lower-level Triton kernel definitions used
+  internally by the operator layer.
+
+Benefits
+--------
+
+- **Portability**: Triton kernels work across GPU architectures without
+  per-target assembly code.
+- **Maintainability**: Written in Python with Triton DSL, making them easier
+  to read and modify than hand-written assembly.
+- **gfx1250 support**: On MI450 (CDNA 4), where hand-tuned ASM kernels are
+  not available, Triton is the primary compute backend alongside HIP.
+
+Other Backends
+--------------
+
+AITER supports multiple kernel backends depending on the GPU architecture and
+operation:
+
+- **ASM** -- Hand-tuned assembly for peak performance on CDNA 3/3.5.
+- **Composable Kernel (CK)** -- C++ template library for fused kernels.
+- **CK Tile** -- Tile-based CK backend for structured operations.
+- **FlyDSL** -- Domain-specific language for peak-performance kernel
+  generation (Meta donation).
+
+The backend selection is automatic based on the GPU architecture and operation
+type. On gfx1250 (MI450), AITER uses Triton+HIP exclusively (no ASM, no CK).