docs(api): stamp the python-sdk version on every generated reference page

gen_api_docs.py now reads the installed cldk version (importlib.metadata) and
emits a `cldk <version>` PyPI badge next to the source badge plus an explicit
"API reference generated from cldk <version>." line in each generated block.
Regenerated against cldk 1.2.0, so the version a reader is looking at is now
unambiguous and updates automatically on each release-driven regeneration.

Author: rahlk

scripts/gen_api_docs.py

@@ -20,6 +20,7 @@
 from __future__ import annotations
 
 import argparse
+import importlib.metadata
 import re
 import sys
 from pathlib import Path
@@ -374,9 +375,33 @@ def get_object(root, dotted: str):
 )
 
 
-def build_body(root, page: dict) -> str:
+def cldk_version() -> str:
+    """The version of the installed `cldk` these pages were generated from."""
+    try:
+        return importlib.metadata.version("cldk")
+    except importlib.metadata.PackageNotFoundError:
+        return ""
+
+
+def version_badge(version: str) -> str:
+    """A shields.io badge stating the python-sdk version, linked to PyPI."""
+    if not version:
+        return ""
+    safe = version.replace("-", "--")
+    return (
+        f"[![cldk {version}]"
+        f"(https://img.shields.io/badge/cldk-{safe}-3776AB?logo=pypi&logoColor=white)]"
+        f"(https://pypi.org/project/cldk/{version}/)"
+    )
+
+
+def build_body(root, page: dict, version: str = "") -> str:
     """The generated symbol reference body (no frontmatter)."""
-    out: list[str] = [GITHUB_BADGE, ""]
+    badge = version_badge(version)
+    header = f"{GITHUB_BADGE} {badge}" if badge else GITHUB_BADGE
+    out: list[str] = [header, ""]
+    if version:
+        out += [f"_API reference generated from cldk {version}._", ""]
     multi = len(page["sections"]) > 1
     for heading, dotted in page["sections"]:
         module = get_object(root, dotted)
@@ -470,9 +495,16 @@ def main() -> int:
         )
         return 1
 
+    version = cldk_version()
+    if version:
+        print(f"generating from cldk {version}")
+    else:
+        print("warning: could not determine the cldk version (is it installed?)",
+              file=sys.stderr)
+
     args.out.mkdir(parents=True, exist_ok=True)
     for page in PAGES:
-        body = build_body(root, page)
+        body = build_body(root, page, version)
         dest = args.out / page["file"]
         text = inject_or_create(dest, page, body)
         mode = "injected into" if dest.exists() and MARK_START in dest.read_text(encoding="utf-8") else "wrote"

src/content/docs/reference/python-api/core.md

@@ -140,7 +140,9 @@ The full generated reference follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+
+_API reference generated from cldk 1.2.0._
 
 Core CLDK module.
 

src/content/docs/reference/python-api/java.md

@@ -106,7 +106,9 @@ follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+
+_API reference generated from cldk 1.2.0._
 
 ## Analysis
 

src/content/docs/reference/python-api/python.md

@@ -123,7 +123,9 @@ follows.
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+
+_API reference generated from cldk 1.2.0._
 
 ## Analysis
 

src/content/docs/reference/python-api/typescript.md

@@ -53,7 +53,9 @@ graph = analysis.get_call_graph()  # -> networkx.DiGraph
 
 <!-- AUTO-GENERATED by scripts/gen_api_docs.py, do not edit by hand. -->
 
-[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk)
+[![Source on GitHub](https://img.shields.io/badge/source-codellm--devkit%2Fpython--sdk-181717?logo=github&logoColor=white)](https://github.com/codellm-devkit/python-sdk) [![cldk 1.2.0](https://img.shields.io/badge/cldk-1.2.0-3776AB?logo=pypi&logoColor=white)](https://pypi.org/project/cldk/1.2.0/)
+
+_API reference generated from cldk 1.2.0._
 
 ## Analysis
 
@@ -958,3 +960,4 @@ A variable / const / let declaration.
 | `end_column` | `int` |  |
 
 <!-- CLDK:API:END -->
+