feat: add cli ref for each command

drbh · drbh · commit 19ef9ce72391 · 2026-02-11T10:54:18.000-05:00
diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml
@@ -45,8 +45,22 @@
       title: Layers
     - local: cli
       title: Kernels CLI
+  title: API Reference
+- sections:
     - local: cli-init
-      title: cli init
+      title: kernels init
+    - local: cli-upload
+      title: kernels upload
     - local: cli-benchmark
-      title: cli benchmark
-  title: API Reference
+      title: kernels benchmark
+    - local: cli-check
+      title: kernels check
+    - local: cli-versions
+      title: kernels versions
+    - local: cli-generate-readme
+      title: kernels generate-readme
+    - local: cli-lock
+      title: kernels lock
+    - local: cli-download
+      title: kernels download
+  title: CLI Reference
diff --git a/docs/source/cli-benchmark.md b/docs/source/cli-benchmark.md
@@ -14,7 +14,7 @@ The command:
 `kernels benchmark` requires extra dependencies:
 
 ```bash
-pip install 'kernels[benchmark]'
+uv pip install 'kernels[benchmark]' # or pip install 'kernels[benchmark]'
 ```
 
 ## Example
diff --git a/docs/source/cli-check.md b/docs/source/cli-check.md
@@ -0,0 +1,65 @@
+# kernels check
+
+Use `kernels check` to verify that a kernel on the Hub meets compliance requirements.
+
+## What It Checks
+
+- Python ABI compatibility (default: 3.9)
+- Operating system compatibility (macOS 15.0+, manylinux_2_28)
+
+## Usage
+
+```bash
+kernels check <repo_id> [--revision <rev>] [--macos <version>] [--manylinux <version>] [--python-abi <version>]
+```
+
+## Installation
+
+`kernels check` requires an additional dependency:
+
+```bash
+uv pip install kernel-abi-check # or pip install kernel-abi-check
+```
+
+## Examples
+
+Check a kernel on the Hub:
+
+```bash
+kernels check kernels-community/flash-attn3
+```
+
+Check a specific revision:
+
+```bash
+kernels check kernels-community/flash-attn3 --revision v2
+```
+
+Check with custom compatibility requirements:
+
+```bash
+kernels check kernels-community/flash-attn3 --python-abi 3.10 --manylinux manylinux_2_31
+```
+
+## Example Output
+
+```text
+Checking variant: torch210-metal-aarch64-darwin
+  Dynamic library _example_kernel_metal_2juixjwdznbhy.abi3.so:
+    🐍 Python ABI 3.9 compatible
+    🍏 compatible with macOS 15.0
+Checking variant: torch29-metal-aarch64-darwin
+  Dynamic library _example_kernel_metal_vtlnpevkb6uum.abi3.so:
+    🐍 Python ABI 3.9 compatible
+    🍏 compatible with macOS 15.0
+```
+
+## Options
+
+| Option         | Default          | Description                         |
+| -------------- | ---------------- | ----------------------------------- |
+| `--revision`   | `main`           | Branch, tag, or commit SHA to check |
+| `--macos`      | `15.0`           | Minimum macOS version to require    |
+| `--manylinux`  | `manylinux_2_28` | Manylinux version to require        |
+| `--python-abi` | `3.9`            | Python ABI version to require       |
+
diff --git a/docs/source/cli-download.md b/docs/source/cli-download.md
@@ -0,0 +1,50 @@
+# kernels download
+
+Use `kernels download` to download kernels that have been locked in a project's `kernels.lock` file.
+
+## Usage
+
+```bash
+kernels download <project_dir> [--all-variants]
+```
+
+## What It Does
+
+- Reads the `kernels.lock` file from the specified project directory
+- Downloads each locked kernel at its pinned revision (SHA)
+- Installs the appropriate variant for your platform (or all variants with `--all-variants`)
+
+## Examples
+
+Download kernels for the current project:
+
+```bash
+kernels download .
+```
+
+Download all build variants (useful for CI or multi-platform builds):
+
+```bash
+kernels download . --all-variants
+```
+
+Download kernels for a specific project:
+
+```bash
+kernels download /path/to/my-project
+```
+
+## Options
+
+| Option           | Description                                                                               |
+| ---------------- | ----------------------------------------------------------------------------------------- |
+| `--all-variants` | Download all build variants of each kernel instead of just the current platform's variant |
+
+## Prerequisites
+
+Your project directory must contain a `kernels.lock` file. Generate one using [`kernels lock`](cli-lock.md).
+
+## See Also
+
+- [kernels lock](cli-lock.md) - Generate the lock file
+- [kernels versions](cli-versions.md) - View available kernel versions
diff --git a/docs/source/cli-generate-readme.md b/docs/source/cli-generate-readme.md
@@ -0,0 +1,61 @@
+# kernels generate-readme
+
+Use `kernels generate-readme` to automatically generate documentation snippets for a kernel's public functions.
+
+## Usage
+
+```bash
+kernels generate-readme <repo_id> [--revision <rev>]
+```
+
+## What It Does
+
+- Downloads the specified kernel from the Hub
+- Inspects the kernel's public API
+- Generates markdown documentation snippets showing function signatures and usage
+
+## Examples
+
+Generate README snippets for a kernel:
+
+```bash
+kernels generate-readme kernels-community/activation > README.md
+```
+
+## Example Output
+
+README.md snippet for `kernels-community/activation`:
+```md
+---
+tags:
+- kernels
+---
+
+## Functions
+
+### Function `fatrelu_and_mul`
+
+`(out: torch.Tensor, x: torch.Tensor, threshold: float = 0.0) -> None`
+
+No documentation available.
+
+### Function `gelu`
+
+`(out: torch.Tensor, x: torch.Tensor) -> None`
+
+No documentation available.
+
+### Function `gelu_and_mul`
+
+`(out: torch.Tensor, x: torch.Tensor) -> None`
+
+No documentation available.
+
+### Function `gelu_fast`
+
+`(out: torch.Tensor, x: torch.Tensor) -> None`
+
+No documentation available.
+
+...
+```
diff --git a/docs/source/cli-lock.md b/docs/source/cli-lock.md
@@ -0,0 +1,78 @@
+# kernels lock
+
+Use `kernels lock` to generate a `kernels.lock` file that pins kernel dependencies to specific revisions.
+
+## Usage
+
+```bash
+kernels lock <project_dir>
+```
+
+## What It Does
+
+- Reads kernel dependencies from `pyproject.toml` under `[tool.kernels.dependencies]`
+- Resolves each kernel to its current revision SHA
+- Writes a `kernels.lock` file with pinned versions and variant information
+
+## Examples
+
+Lock kernels in the current project:
+
+```bash
+kernels lock .
+```
+
+Lock kernels in a specific project:
+
+```bash
+kernels lock /path/to/my-project
+```
+
+## pyproject.toml Format
+
+Add your kernel dependencies to `pyproject.toml`:
+
+```toml
+[tool.kernels.dependencies]
+"kernels-community/activation" = 1
+```
+
+The version can be:
+
+- A version number (e.g., `1`, `2`)
+
+## kernels.lock Format
+
+The generated lock file contains:
+
+```json
+[
+  {
+    "repo_id": "kernels-community/activation",
+    "sha": "ece277f908b9453112722d584fee4b5696f21c49",
+    "variants": {
+      "torch210-cu128-x86_64-windows": {
+        "hash": "sha256-cbf085e1d297d990d9cb074fb5079ff48e9682c729f53a0899a36b5164a6fb45",
+        "hash_type": "git_lfs_concat"
+      },
+      // ...
+      "torch29-metal-aarch64-darwin": {
+        "hash": "sha256-9f665b54a53246a7d3627422f8a0d41d7956dc5409043dbd14c4ec0327aea310",
+        "hash_type": "git_lfs_concat"
+      }
+    }
+  }
+]
+```
+
+## Workflow
+
+1. Add dependencies to `pyproject.toml`
+2. Run `kernels lock .` to generate the lock file
+3. Commit both `pyproject.toml` and `kernels.lock`
+4. Use `kernels download .` to install locked kernels
+
+## See Also
+
+- [kernels download](cli-download.md) - Download locked kernels
+- [kernels versions](cli-versions.md) - View available kernel versions
diff --git a/docs/source/cli-upload.md b/docs/source/cli-upload.md
@@ -0,0 +1,62 @@
+# kernels upload
+
+Use `kernels upload` to upload built kernels to the Hugging Face Hub.
+
+## Usage
+
+```bash
+kernels upload <kernel_dir> --repo-id <repo_id> [--branch <branch>] [--private]
+```
+
+## What It Does
+
+- Creates a repository on the Hub if it doesn't exist
+- Uploads the kernel build artifacts from the specified directory
+- If a build variant already exists in the repo, replaces the existing files
+
+## Examples
+
+Upload a kernel build:
+
+```bash
+kernels upload ./build --repo-id my-username/my-kernel
+```
+
+Upload to a specific branch:
+
+```bash
+kernels upload ./build --repo-id my-username/my-kernel --branch dev
+```
+
+Upload as a private repository:
+
+```bash
+kernels upload ./build --repo-id my-username/my-kernel --private
+```
+
+## Options
+
+| Option      | Required | Description                                             |
+| ----------- | -------- | ------------------------------------------------------- |
+| `--repo-id` | Yes      | Repository ID on the Hub (e.g., `username/kernel-name`) |
+| `--branch`  | No       | Upload to a specific branch instead of main             |
+| `--private` | No       | Create the repository as private                        |
+
+## Prerequisites
+
+You must be authenticated with the Hugging Face Hub:
+
+```bash
+huggingface-cli login
+```
+
+## Notes
+
+- The `kernel_dir` should contain the build output (typically the `build/` directory from your kernel project)
+- If uploading a new variant to an existing repo, only that variant's files are replaced
+- Make sure your kernel passes [`kernels check`](cli-check.md) before uploading
+
+## See Also
+
+- [kernels check](cli-check.md) - Verify kernel compliance before uploading
+- [kernels init](cli-init.md) - Create a new kernel project
diff --git a/docs/source/cli-versions.md b/docs/source/cli-versions.md
@@ -0,0 +1,34 @@
+# kernels versions
+
+Use `kernels versions` to list all available versions of a kernel on the Hub.
+
+## Usage
+
+```bash
+kernels versions <repo_id>
+```
+
+## Examples
+
+List versions of a kernel:
+
+```bash
+kernels versions kernels-community/activation
+```
+
+## Example Output
+
+```text
+Version 1: torch210-cu128-x86_64-windows, torch210-cxx11-cu126-x86_64-linux, torch210-cxx11-cu128-x86_64-linux, torch210-cxx11-cu130-x86_64-linux, torch210-metal-aarch64-darwin ✅, torch27-cxx11-cu118-x86_64-linux, torch27-cxx11-cu126-x86_64-linux, torch27-cxx11-cu128-aarch64-linux, torch27-cxx11-cu128-x86_64-linux, torch28-cxx11-cu126-aarch64-linux, torch28-cxx11-cu126-x86_64-linux, torch28-cxx11-cu128-aarch64-linux, torch28-cxx11-cu128-x86_64-linux, torch28-cxx11-cu129-aarch64-linux, torch28-cxx11-cu129-x86_64-linux, torch29-cxx11-cu126-aarch64-linux, torch29-cxx11-cu126-x86_64-linux, torch29-cxx11-cu128-aarch64-linux, torch29-cxx11-cu128-x86_64-linux, torch29-cxx11-cu130-aarch64-linux, torch29-cxx11-cu130-x86_64-linux, torch29-metal-aarch64-darwin
+```
+
+## Use Cases
+
+- Check which versions are available before locking dependencies
+- Find the latest version of a kernel
+- Identify version SHAs for pinning in `pyproject.toml`
+
+## See Also
+
+- [kernels lock](cli-lock.md) - Lock kernel versions in your project
+- [kernels download](cli-download.md) - Download locked kernels
diff --git a/docs/source/cli.md b/docs/source/cli.md
diff --git a/docs/source/installation.md b/docs/source/installation.md
