Add hasApi flag to package manifest and gate API Reference link on it

Author: milanofthe

scripts/build.py

@@ -467,7 +467,7 @@ def generate_package_manifest(package_id: str, dry_run: bool = False):
     version_tags.sort(key=parse_version, reverse=True)
     latest_tag = version_tags[0]
 
-    # Build versions list with release dates and examples availability
+    # Build versions list with release dates, examples, and API availability
     versions = []
     for tag in version_tags:
         released = get_tag_date(repo_path, tag)
@@ -481,10 +481,23 @@ def generate_package_manifest(package_id: str, dry_run: bool = False):
                     has_examples = len(version_manifest.get("notebooks", [])) > 0
             except Exception:
                 pass
+        # Check if this version has an API extract. Packages whose source is
+        # essentially empty (e.g. an early scaffolded stub) produce no api.json,
+        # in which case the frontend must not advertise an "API Reference" link.
+        api_path = output_dir / tag / "api.json"
+        has_api = False
+        if api_path.exists():
+            try:
+                with open(api_path, "r", encoding="utf-8") as f:
+                    api_data = json.load(f)
+                    has_api = bool(api_data.get("modules"))
+            except Exception:
+                pass
         versions.append({
             "tag": tag,
             "released": released,
             "hasExamples": has_examples,
+            "hasApi": has_api,
         })
 
     # Check if roadmap exists

src/lib/api/versions.ts

@@ -6,6 +6,7 @@ export interface VersionInfo {
 	tag: string;
 	released: string;
 	hasExamples?: boolean;
+	hasApi?: boolean;
 }
 
 export interface PackageManifest {
@@ -108,6 +109,16 @@ export function versionHasExamples(tag: string, manifest: PackageManifest): bool
 	return version?.hasExamples ?? false;
 }
 
+/**
+ * Check if a version has an extracted API. Returns true when the flag is
+ * missing (older manifests) so we err on the side of showing the link.
+ */
+export function versionHasApi(tag: string, manifest: PackageManifest): boolean {
+	const normalized = normalizeTag(tag);
+	const version = manifest.versions.find((v) => v.tag === normalized);
+	return version?.hasApi ?? true;
+}
+
 /**
  * Check if a package has roadmap items
  */

src/lib/components/layout/Sidebar.svelte

@@ -14,7 +14,7 @@
 	import { searchTarget } from '$lib/stores/searchNavigation';
 	import { exampleGroupsStore } from '$lib/stores/examplesContext';
 	import type { PackageManifest } from '$lib/api/versions';
-	import { versionHasExamples, packageHasRoadmap } from '$lib/api/versions';
+	import { versionHasExamples, versionHasApi, packageHasRoadmap } from '$lib/api/versions';
 	import { SearchInput, SearchResult as SearchResultComponent } from '$lib/components/search';
 
 	interface Props {
@@ -30,17 +30,22 @@
 		manifest && currentTag ? versionHasExamples(currentTag, manifest) : false
 	);
 
+	// Check if current version has API (false for packages with no Python source)
+	let hasApi = $derived(
+		manifest && currentTag ? versionHasApi(currentTag, manifest) : !!manifest
+	);
+
 	// Check if package has roadmap items
 	let hasRoadmap = $derived(manifest ? packageHasRoadmap(manifest) : false);
 
 	// Filter sidebar items based on availability
-	// - Hide API Reference if no manifest (no versioned docs exist)
+	// - Hide API Reference if version has no extracted API
 	// - Hide Examples if current version has no examples
 	// - Hide Roadmap if package has no roadmap items
 	let items = $derived(
 		getSidebarItems(packageId, currentTag).filter(
 			(item) =>
-				(item.title !== 'API Reference' || manifest) &&
+				(item.title !== 'API Reference' || hasApi) &&
 				(item.title !== 'Examples' || hasExamples) &&
 				(item.title !== 'Roadmap' || hasRoadmap)
 		)

src/lib/components/pages/PackageOverview.svelte

@@ -6,7 +6,7 @@
 	import NotebookCell from '$lib/components/common/NotebookCell.svelte';
 	import { packages, type PackageId, type InstallOption } from '$lib/config/packages';
 	import { copyToClipboard } from '$lib/utils/clipboard';
-	import { type PackageManifest, versionHasExamples, packageHasRoadmap } from '$lib/api/versions';
+	import { type PackageManifest, versionHasExamples, versionHasApi, packageHasRoadmap } from '$lib/api/versions';
 	import { packageVersionsStore } from '$lib/stores/packageVersionsStore';
 
 	/**
@@ -70,7 +70,9 @@
 	}
 
 	// Reactively compute availability based on manifest and selectedTag
-	let apiAvailable = $derived(manifest !== null && selectedTag !== null);
+	let apiAvailable = $derived(
+		manifest && selectedTag ? versionHasApi(selectedTag, manifest) : false
+	);
 	let examplesAvailable = $derived(
 		manifest && selectedTag ? versionHasExamples(selectedTag, manifest) : false
 	);