Kernel docs followups

docs/source/_toctree.yml

@@ -67,6 +67,4 @@
       title: kernels download
     - local: cli-skills
       title: kernels skills
-    - local: cli-create-and-upload-card
-      title: kernels create-and-upload-card
   title: CLI Reference

docs/source/builder/writing-kernels.md

@@ -330,3 +330,18 @@ $ nix run .#ciTests.torch210-cxx11-cpu-x86_64-linux
 
 When running the tests on a non-NixOS systems, make sure that
 [the CUDA driver library can be found](https://danieldk.eu/Software/Nix/Nix-CUDA-on-non-NixOS-systems#solutions).
+
+## Kernel docs
+
+We provide a utility to generate a system card for a given kernel, utilizing
+information from its `build.toml` and metadata. This system card provides a
+reasonable starting point and is meant to be edited afterward by the kernel
+developer.
+
+The template card is generated as a part of [`kernels init`](../cli-init.md)
+command and is serialized in the root directory of the kernel.
+
+The card will be filled automatically by the builder when using the
+`build-and-upload` or `build-and-copy` command. It will be serialized
+to the `build` sub-directory inside the main kernel directory. It
+will be uploaded as `README.md` to the Hub.

docs/source/cli-init.md

@@ -15,6 +15,8 @@ This creates a new directory in the current working directory with the (normaliz
 - Downloads a project template and replaces placeholders in file names, paths, and file contents
 - Optionally restricts enabled backends (updates `build.toml` and removes unused backend folders)
 - Initializes a Git repo and stages the files (`git init`, `git add .`)
+- Initializes a templated system card for the kernel which is meant for the
+kernel developer to further modify
 
 ## Examples
 

kernels/pyproject.toml

@@ -11,6 +11,7 @@ readme = "README.md"
 requires-python = ">= 3.9"
 dependencies = [
   "huggingface_hub>=0.26.0,<2.0",
+  "Jinja2>=3.1.5",
   "packaging>=20.0",
   "pyyaml>=6",
   "tomli>=2.0; python_version<'3.11'",

kernels/src/kernels/cli/__init__.py

@@ -4,27 +4,31 @@
 import sys
 from pathlib import Path
 
+from huggingface_hub import ModelCard, ModelCardData
+
 from kernels.cli.doc import generate_readme_for_kernel
 from kernels.cli.init import parse_kernel_name, run_init
+from kernels.cli.kernel_card_utils import (
+    DESCRIPTION,
+    KERNEL_CARD_TEMPLATE_PATH,
+    LIBRARY_NAME,
+    _build_kernel_card_vars,
+    _parse_repo_id,
+    _update_kernel_card_license,
+)
 from kernels.cli.skills import add_skill
 from kernels.cli.upload import upload_kernels_dir
 from kernels.cli.versions import print_kernel_versions
 from kernels.compat import tomllib
-from kernels.kernel_card_utils import (
-    _load_or_create_kernel_card,
-    _update_benchmark,
-    _update_kernel_card_available_funcs,
-    _update_kernel_card_backends,
-    _update_kernel_card_license,
-    _update_kernel_card_usage,
-)
 from kernels.lockfile import KernelLock, get_kernel_locks
 from kernels.utils import (
     KNOWN_BACKENDS,
     install_kernel,
     install_kernel_all_variants,
 )
 
+SYSTEM_CARD_PATH = "CARD.md"
+
 
 def main():
     parser = argparse.ArgumentParser(
@@ -247,36 +251,22 @@ def main():
     )
     init_parser.set_defaults(func=run_init)
 
-    repocard_parser = subparsers.add_parser(
-        "create-and-upload-card",
-        help="Create and optionally upload a kernel card.",
+    fill_card_parser = subparsers.add_parser(
+        "fill-card",
+        help="Fill a system card template based on the `build` information and save it.",
     )
-    repocard_parser.add_argument(
+    fill_card_parser.add_argument(
         "kernel_dir",
         type=str,
         help="Path to the kernels source.",
     )
-    repocard_parser.add_argument(
-        "--card-path", type=str, required=True, help="Path to save the card to."
-    )
-    repocard_parser.add_argument(
+    fill_card_parser.add_argument(
         "--description",
         type=str,
         default=None,
         help="Description to introduce the kernel.",
     )
-    repocard_parser.add_argument(
-        "--repo-id",
-        type=str,
-        default=None,
-        help="If specified it will be pushed to a repository on the Hub.",
-    )
-    repocard_parser.add_argument(
-        "--create-pr",
-        action="store_true",
-        help="If specified it will create a PR on the `repo_id`.",
-    )
-    repocard_parser.set_defaults(func=create_and_upload_card)
+    fill_card_parser.set_defaults(func=fill_kernel_card)
 
     args = parser.parse_args()
     args.func(args)
@@ -348,34 +338,31 @@ def upload_kernels(args):
     )
 
 
-def create_and_upload_card(args):
-    if not args.repo_id and args.create_pr:
-        raise ValueError("`create_pr` cannot be True when `repo_id` is None.")
-
+def fill_kernel_card(args):
     kernel_dir = Path(args.kernel_dir).resolve()
-    kernel_card = _load_or_create_kernel_card(
-        kernel_description=args.description, license="apache-2.0"
-    )
+    if not (kernel_dir / "build.toml").exists():
+        raise ValueError(
+            f"`build.toml` was not found in {str(kernel_dir)}. Cannot proceed."
+        )
 
-    updated_card = _update_kernel_card_usage(
-        kernel_card=kernel_card, local_path=kernel_dir, repo_id=args.repo_id
-    )
-    updated_card = _update_kernel_card_available_funcs(
-        kernel_card=kernel_card, local_path=kernel_dir
-    )
-    updated_card = _update_kernel_card_backends(
-        kernel_card=kernel_card, local_path=kernel_dir
-    )
-    updated_card = _update_benchmark(kernel_card=kernel_card, local_path=kernel_dir)
-    updated_card = _update_kernel_card_license(
-        kernel_card=kernel_card, local_path=kernel_dir
-    )
+    card_path = kernel_dir / "build" / SYSTEM_CARD_PATH
 
-    card_path = args.card_path
-    updated_card.save(card_path)
+    repo_id_from_build = _parse_repo_id(kernel_dir)
+    repo_id = repo_id_from_build or "{repo_id}"
 
-    if args.repo_id:
-        updated_card.push_to_hub(repo_id=args.repo_id, create_pr=args.create_pr)
+    dynamic_vars = _build_kernel_card_vars(kernel_dir, repo_id=repo_id)
+    description = (args.description or DESCRIPTION).format(repo_id=repo_id)
+
+    card_data = ModelCardData(library_name=LIBRARY_NAME)
+    updated_card = ModelCard.from_template(
+        card_data=card_data,
+        template_path=str(KERNEL_CARD_TEMPLATE_PATH),
+        kernel_description=description,
+        **dynamic_vars,
+    )
+    _update_kernel_card_license(updated_card, kernel_dir)
+    card_path.parent.mkdir(parents=True, exist_ok=True)
+    updated_card.save(card_path)
 
 
 class _JSONEncoder(json.JSONEncoder):

kernels/src/kernels/cli/card_template.md

@@ -0,0 +1,38 @@
+---
+{{ card_data }}
+---
+
+<!-- This model card has automatically been generated. You
+should probably proofread and complete it, then remove this comment. -->
+
+{{ kernel_description }}
+
+## How to use
+
+{{ usage_example }}
+
+## Available functions
+
+{{ available_functions }}
+
+## Supported backends
+
+{{ supported_backends }}
+{% if cuda_capabilities %}
+
+## CUDA Capabilities
+
+{{ cuda_capabilities }}
+{% endif %}
+
+## Benchmarks
+
+{{ benchmark_content }}
+
+## Source code
+
+{{ source_code }}
+
+## Notes
+
+{{ notes }}

kernels/src/kernels/cli/init.py

@@ -12,8 +12,11 @@
 from huggingface_hub import snapshot_download
 from huggingface_hub.utils import disable_progress_bars
 
+from kernels.cli.kernel_card_utils import KERNEL_CARD_TEMPLATE_PATH
 from kernels.utils import KNOWN_BACKENDS
 
+SYSTEM_CARD_FILENAME = "CARD.md"
+
 KERNEL_NAME_PATTERN = re.compile(r"^[a-z][-a-z0-9]*[a-z0-9]$")
 
 
@@ -98,6 +101,9 @@ def run_init(args: Namespace) -> None:
 
         _remove_backend_dirs(target_dir, backends)
 
+    # Generate the card template
+    _initialize_card(target_dir)
+
     # Initialize git repo (required for Nix flakes)
     subprocess.run(["git", "init"], cwd=target_dir, check=True, capture_output=True)
     subprocess.run(["git", "add", "."], cwd=target_dir, check=True, capture_output=True)
@@ -111,6 +117,11 @@ def run_init(args: Namespace) -> None:
     print("uv run example.py")
 
 
+def _initialize_card(target_dir: Path) -> None:
+    card_path = target_dir / SYSTEM_CARD_FILENAME
+    shutil.copy(KERNEL_CARD_TEMPLATE_PATH, card_path)
+
+
 def _init_from_local_template(
     template_dir: Path,
     target_dir: Path,