fix: update relative paths and readme cleanups (#240)

Author: drbh

README.md

@@ -1,11 +1,11 @@
 # kernels
 
 <div align="center">
-<img src="https://github.com/user-attachments/assets/64a652f3-0cd3-4829-b3c1-df13f7933569" width="450" height="450" alt="kernel-builder logo">
+<img src="https://github.com/user-attachments/assets/4b5175f3-1d60-455b-8664-43b2495ee1c3" width="450" height="450" alt="kernel-builder logo">
 <p align="center">
     <a href="https://pypi.org/project/kernels"><img alt="PyPI - Version" src="https://img.shields.io/pypi/v/kernels"></a>
     <a href="https://github.com/huggingface/kernels/tags"><img alt="GitHub tag" src="https://img.shields.io/github/v/tag/huggingface/kernels"></a>
-    <a href="https://github.com/huggingface/kernels/actions/workflows/docker-build-push.yaml"><img alt="Test kernels" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernels/test.yml?label=test"></a>
+    <a href="https://github.com/huggingface/kernels/actions/workflows/test_kernels.yaml"><img alt="Test kernels" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernels/test_kernels.yaml?label=test"></a>
 
 </p>
 </div>

builder/README.md

@@ -1,14 +1,10 @@
 # kernel-builder
 
-<div align="center">
-<img src="https://github.com/user-attachments/assets/4b5175f3-1d60-455b-8664-43b2495ee1c3" width="450" height="450" alt="kernel-builder logo">
-<p align="center">
-    <a href="https://github.com/huggingface/kernel-builder/actions/workflows/docker-build-push.yaml"><img alt="Build and Push Docker Image" src="https://img.shields.io/github/actions/workflow/status/huggingface/kernel-builder/docker-build-push.yaml?label=docker"></a>
-    <a href="https://github.com/huggingface/kernel-builder/tags"><img alt="GitHub tag" src="https://img.shields.io/github/v/tag/huggingface/kernel-builder"></a>
-    <a href="https://github.com/huggingface/kernel-builder/pkgs/container/kernel-builder"><img alt="GitHub package" src="https://img.shields.io/badge/container-ghcr.io-blue"></a>
-</p>
-</div>
-<hr/>
+The kernel-builder is a build system for creating Hub-compatible compute kernels. It handles the complexity of building kernels that are:
+
+- Portable: kernels can be loaded from paths outside `PYTHONPATH`.
+- Unique: multiple versions of the same kernel can be loaded in the same Python process.
+- Compatible: kernels support all recent versions of Python and the different PyTorch build configurations (various CUDA versions and C++ ABIs).
 
 **Note:** Torch 2.10 builds are still based on PyTorch release candidates.
 Typically the ABI does not break during release candidates. If it does,
@@ -70,14 +66,14 @@ See [dockerfiles/README.md](./dockerfiles/README.md) for more options, including
 
 # 📚 Documentation
 
-- [Writing Hub kernels](./docs/writing-kernels.md)
-- [Building kernels with Nix](./docs/nix.md)
+- [Writing Hub kernels](../docs/source/builder/writing-kernels.md)
+- [Building kernels with Nix](../docs/source/builder/nix.md)
 - Framework-specific notes:
-  - [Metal](docs/metal.md)
-- [Building kernels with Docker](./docs/docker.md) (for systems without Nix)
-- [Local kernel development](docs/local-dev.md) (IDE integration)
-- [Kernel security](./docs/security.md)
-- [Why Nix?](./docs/why-nix.md)
+  - [Metal](../docs/source/builder/metal.md)
+- [Building kernels with Docker](../docs/source/builder/docker.md) (for systems without Nix)
+- [Local kernel development](../docs/source/builder/local-dev.md) (IDE integration)
+- [Kernel security](../docs/source/builder/security.md)
+- [Why Nix?](../docs/source/builder/why-nix.md)
 
 ## Credits
 

docs/source/builder/local-dev.md

@@ -46,6 +46,6 @@ $ pip install --no-build-isolation -e .
 **Warnings:**
 
 - Kernels built in this way should **not** be published on the Kernel
-  Hub. They do not fulfill the [kernel requirements](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
+  Hub. They do not fulfill the [kernel requirements](../kernel-requirements.md).
 - Do not add the generated files to Git. `build2cmake` has regular updates
   and you generally want to use files generated by the latest version.

docs/source/builder/nix.md

@@ -12,7 +12,7 @@ We recommend installing Nix in the following way:
 
 The easiest way get all the Nix functionality is by putting a
 `flake.nix` in your kernel repository. To do so, copy
-[`examples/relu/flake.nix`](../examples/relu/flake.nix) into the
+[`examples/relu/flake.nix`](https://github.com/huggingface/kernels/blob/main/builder/examples/relu/flake.nix) into the
 same directory as your `build.toml` file. Then run `nix flake update`.
 This generates a `flake.lock` file that pins the kernel builder
 and _all_ its transitive dependencies. Commit both `flake.nix`

docs/source/builder/writing-kernels.md

@@ -30,9 +30,9 @@ of CMake or setuptools.
 
 This page describes the directory layout of a kernel-builder project, the
 format of the `build.toml` file, and some additional Python glue that
-`kernel-builder` provides. We will use a [simple ReLU kernel](../examples/relu)
+`kernel-builder` provides. We will use a [simple ReLU kernel](https://github.com/huggingface/kernels/tree/main/builder/examples/relu)
 as the running example. After reading this page, you may also want to have
-a look at the more realistic [ReLU kernel with backprop and `torch.compile`](../examples/relu-backprop-compile)
+a look at the more realistic [ReLU kernel with backprop and `torch.compile`](https://github.com/huggingface/kernels/tree/main/builder/examples/relu-backprop-compile)
 support.
 
 ## Kernel project layout
@@ -107,12 +107,12 @@ depends = [ "torch" ]
 
 - `maxver`: the maximum CUDA toolkit version (inclusive). This option
   _must not_ be set under normal circumstances, since it can exclude Torch
-  build variants that are [required for compliant kernels](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
+  build variants that are [required for compliant kernels](../kernel-requirements.md).
   This option is provided for kernels that cause compiler errors on
   newer CUDA toolkit versions.
 - `minver`: the minimum required CUDA toolkit version. This option
   _must not_ be set under normal circumstances, since it can exclude Torch
-  build variants that are [required for compliant kernels](https://github.com/huggingface/kernels/blob/main/docs/kernel-requirements.md).
+  build variants that are [required for compliant kernels](../kernel-requirements.md).
   This option is provided for kernels that require functionality only
   provided by newer CUDA toolkits.
 
@@ -145,7 +145,7 @@ The following options can be set for a kernel:
   supported backends are `cpu`, `cuda`, `metal`, `rocm`, and `xpu`.
   **The `cpu` backend is currently experimental and might still change.**
 - `depends` (required): a list of dependencies. The supported dependencies
-  are listed in [`deps.nix`](../lib/deps.nix).
+  are listed in [`deps.nix`](https://github.com/huggingface/kernels/blob/main/builder/lib/deps.nix).
 - `src` (required): a list of source files and headers.
 - `include` (optional): include directories relative to the project root.
   Default: `[]`.