Improve API documentation layout

Signed-off-by: Bradley Dice <bdice@bradleydice.com>

Author: bdice

api.md

@@ -1,17 +1,16 @@
-# RAPIDS API Docs
+# RAPIDS API Documentation
 
-Access our current docs for the RAPIDS projects below. Docs are available in
-both "stable" and "nightly" versions. The description of each is below to help
-select the docs that fit your needs.
+Explore documentation for current and previous RAPIDS releases. Each project
+card links to its available documentation versions and related resources.
 
-STABLE
-: Current release docs; considered to be stable.
+Stable
+: Documentation for the current release, recommended for most users.
 
-NIGHTLY
-: Work-in-progress release docs; considered to be unstable and released nightly.
+Nightly
+: Documentation for the upcoming release, generated from development branches.
 
-LEGACY
-: Previous release docs; available for reference.
+Legacy
+: Documentation for the previous release, retained for reference.
 
 ## RAPIDS APIs
 

extensions/rapids_docs.py

@@ -80,33 +80,49 @@ def _version_label(project: dict, version_name: str, releases: dict) -> str:
 
 
 def _api_docs(data: dict, section: str) -> str:
-    blocks = []
+    cards = []
     for project in data["docs"][section].values():
         if project.get("hidden", False):
             continue
         versions = []
         for name in ("stable", "nightly", "legacy"):
             if project["versions"].get(name) == 1:
                 label = _version_label(project, name, data["releases"])
-                versions.append(f"**[{name} ({label})](/api/{project['path']}/{name}/)**")
+                versions.append(f"[{name.title()} ({label})](/api/{project['path']}/{name}/)")
         links = []
         if project.get("cllink"):
-            links.append(f"**[changelog]({project['cllink']})**")
-        links.append(f"**[github]({project['ghlink']})**")
-        blocks.append(
+            links.append(f"[Changelog]({project['cllink']})")
+        links.append(f"[GitHub]({project['ghlink']})")
+        footer = []
+        if versions:
+            footer.extend(["**Documentation:** " + " · ".join(versions), ""])
+        footer.append("**Resources:** " + " · ".join(links))
+        cards.append(
             "\n".join(
                 [
-                    f"### {project['name']}",
+                    f":::{{grid-item-card}} {project['name']}",
+                    ":class-card: rapids-api-card",
+                    ":class-title: rapids-api-card-title",
+                    ":class-footer: rapids-api-card-footer",
                     "",
                     project["desc"],
                     "",
-                    "#### DOCS" + (" " + " | ".join(versions) if versions else ""),
-                    "",
-                    "#### LINKS " + " | ".join(links),
+                    "+++",
+                    *footer,
+                    ":::",
                 ]
             )
         )
-    return "\n\n".join(blocks)
+    return "\n".join(
+        [
+            "::::{grid} 1 1 2 2",
+            ":gutter: 2",
+            ":class-container: rapids-api-grid",
+            "",
+            "\n\n".join(cards),
+            "::::",
+        ]
+    )
 
 
 def _compute_capability(cuda: dict) -> str:

sphinx/_static/css/custom.css

@@ -58,6 +58,22 @@
   height: 100%;
 }
 
+.rapids-api-grid .sd-card {
+  height: 100%;
+}
+
+.rapids-api-card-title {
+  font-size: 1.15rem;
+}
+
+.rapids-api-card-footer p {
+  margin-bottom: 0.35rem;
+}
+
+.rapids-api-card-footer p:last-child {
+  margin-bottom: 0;
+}
+
 @media (max-width: 720px) {
   .selector-bg .container-padding {
     min-width: 40rem;

tests/test_rendering.py

@@ -16,8 +16,13 @@ def test_data_driven_content() -> None:
     nightly_version = data["releases"]["nightly"]["version"]
 
     api = rapids_docs._api_docs(data, "apis")
-    assert f"stable ({stable_version})" in api
+    assert f"Stable ({stable_version})" in api
     assert "/api/cudf/stable/" in api
+    assert "::::{grid} 1 1 2 2" in api
+    assert ":::{grid-item-card} cuDF" in api
+    assert "**Documentation:**" in api
+    assert "[GitHub]" in api
+    assert "DOCS" not in api
 
     inactive = rapids_docs._api_docs(data, "inactive-projects")
     inactive_project = next(
@@ -26,7 +31,7 @@ def test_data_driven_content() -> None:
         if not project.get("hidden", False) and project["versions"].get("stable") == 1
     )
     inactive_version = rapids_docs._version_label(inactive_project, "stable", data["releases"])
-    assert f"stable ({inactive_version})" in inactive
+    assert f"Stable ({inactive_version})" in inactive
 
     platform = rapids_docs._platform_support(data)
     platform_release = data["platform_support"]["releases"][0]