Simplify gRPC API navigation

docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin.mdx

@@ -1,5 +1,5 @@
 ---
-title: "v2.admin"
+title: "Details and history"
 description: "Package-level overview for com.daml.ledger.api.v2.admin."
 ---
 
@@ -10,7 +10,7 @@ description: "Package-level overview for com.daml.ledger.api.v2.admin."
   <p class="x2mdx-ref-eyebrow">Protobuf Package</p>
 
 
-  <h1 class="x2mdx-ref-title">v2.admin</h1>
+  <h1 class="x2mdx-ref-title">Details and history</h1>
 
 
   <p class="x2mdx-ref-summary">6 services, 28 endpoints, 78 messages, 3 enums</p>

docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1.mdx

@@ -1,5 +1,5 @@
 ---
-title: "v2.interactive.transaction.v1"
+title: "Details and history"
 description: "Package-level overview for com.daml.ledger.api.v2.interactive.transaction.v1."
 ---
 
@@ -10,7 +10,7 @@ description: "Package-level overview for com.daml.ledger.api.v2.interactive.tran
   <p class="x2mdx-ref-eyebrow">Protobuf Package</p>
 
 
-  <h1 class="x2mdx-ref-title">v2.interactive.transaction.v1</h1>
+  <h1 class="x2mdx-ref-title">Details and history</h1>
 
 
   <p class="x2mdx-ref-summary">0 services, 0 endpoints, 5 messages</p>

docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive.mdx

@@ -1,5 +1,5 @@
 ---
-title: "v2.interactive"
+title: "Details and history"
 description: "Package-level overview for com.daml.ledger.api.v2.interactive."
 ---
 
@@ -10,7 +10,7 @@ description: "Package-level overview for com.daml.ledger.api.v2.interactive."
   <p class="x2mdx-ref-eyebrow">Protobuf Package</p>
 
 
-  <h1 class="x2mdx-ref-title">v2.interactive</h1>
+  <h1 class="x2mdx-ref-title">Details and history</h1>
 
 
   <p class="x2mdx-ref-summary">1 services, 6 endpoints, 28 messages, 1 enums</p>

docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing.mdx

@@ -1,5 +1,5 @@
 ---
-title: "v2.testing"
+title: "Details and history"
 description: "Package-level overview for com.daml.ledger.api.v2.testing."
 ---
 
@@ -10,7 +10,7 @@ description: "Package-level overview for com.daml.ledger.api.v2.testing."
   <p class="x2mdx-ref-eyebrow">Protobuf Package</p>
 
 
-  <h1 class="x2mdx-ref-title">v2.testing</h1>
+  <h1 class="x2mdx-ref-title">Details and history</h1>
 
 
   <p class="x2mdx-ref-summary">1 services, 2 endpoints, 3 messages</p>

docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2.mdx

@@ -1,5 +1,5 @@
 ---
-title: "v2"
+title: "Details and history"
 description: "Package-level overview for com.daml.ledger.api.v2."
 ---
 
@@ -10,7 +10,7 @@ description: "Package-level overview for com.daml.ledger.api.v2."
   <p class="x2mdx-ref-eyebrow">Protobuf Package</p>
 
 
-  <h1 class="x2mdx-ref-title">v2</h1>
+  <h1 class="x2mdx-ref-title">Details and history</h1>
 
 
   <p class="x2mdx-ref-summary">9 services, 20 endpoints, 115 messages, 8 enums</p>

scripts/generate_grpc_ledger_api_reference.py

@@ -477,7 +477,7 @@ def build_nav_group(
     ):
         package_ref = canton_protobuf_history.docs_json_page_ref(package_page, docs_json_path)
         refs.add(package_ref)
-        package_pages: list[Any] = [package_ref]
+        package_pages: list[Any] = []
         package_operation_dir = output_dir / package_page.stem
         service_groups: list[Any] = []
         if package_operation_dir.is_dir():
@@ -501,16 +501,33 @@ def build_nav_group(
                     }
                 )
         if service_groups:
-            package_pages.append({"group": "Services", "pages": service_groups})
+            package_pages.extend(service_groups)
+        package_pages.append(package_ref)
         package_groups.append({"group": mdx_title(package_page), "pages": package_pages})
 
     pages: list[Any] = []
-    if package_groups:
-        pages.append({"group": "Packages", "pages": package_groups})
+    pages.extend(package_groups)
     pages.append(details_ref)
     return {"group": GROUP_LABEL, "pages": pages}, refs
 
 
+def retitle_package_detail_pages(*, output_dir: Path, page_paths: list[Path]) -> None:
+    for package_page in sorted(
+        (path for path in page_paths if path.parent == output_dir),
+        key=lambda path: path.name,
+    ):
+        if package_page.name == "details.mdx":
+            continue
+        title = mdx_title(package_page)
+        replace_text(
+            package_page,
+            [
+                (f'title: "{title}"', f'title: "{DETAILS_LABEL}"'),
+                (f"<h1 class=\"x2mdx-ref-title\">{html_text(title)}</h1>", f"<h1 class=\"x2mdx-ref-title\">{DETAILS_LABEL}</h1>"),
+            ],
+        )
+
+
 def insert_group(items: list[Any], *, group: dict[str, Any], after_group: str | None) -> None:
     if after_group:
         for index, item in enumerate(items):
@@ -520,6 +537,22 @@ def insert_group(items: list[Any], *, group: dict[str, Any], after_group: str |
     items.append(group)
 
 
+def ledger_api_target_pages(items: list[Any], *, parent_groups: list[str]) -> list[Any]:
+    if parent_groups:
+        return canton_protobuf_history.ensure_group_path(items, parent_groups)
+    ledger_group = next(
+        (item for item in items if isinstance(item, dict) and item.get("group") == reference_nav.LEDGER_API_PARENT_GROUP),
+        None,
+    )
+    if ledger_group is None:
+        return items
+    pages = ledger_group.get("pages")
+    if not isinstance(pages, list):
+        pages = []
+        ledger_group["pages"] = pages
+    return pages
+
+
 def update_docs_navigation(
     *,
     docs_json_path: Path,
@@ -530,30 +563,24 @@ def update_docs_navigation(
     page_paths: list[Path],
 ) -> None:
     docs = load_json(docs_json_path)
-    navigation = docs.get("navigation")
-    if not isinstance(navigation, dict):
-        raise ValueError(f"docs.json navigation must be an object: {docs_json_path}")
-    dropdowns = navigation.get("dropdowns")
-    if not isinstance(dropdowns, list):
-        raise ValueError(f"docs.json navigation.dropdowns must be a list: {docs_json_path}")
-    dropdown = next((item for item in dropdowns if isinstance(item, dict) and item.get("dropdown") == dropdown_label), None)
-    if dropdown is None:
-        raise ValueError(f"Dropdown not found in docs.json: {dropdown_label}")
-    pages = dropdown.get("pages")
-    if not isinstance(pages, list):
-        raise ValueError(f"Dropdown does not expose a pages list: {dropdown_label}")
+    nav_container = reference_nav.find_navigation_container(
+        docs,
+        label=dropdown_label,
+        docs_json_path=docs_json_path,
+    )
+    pages = reference_nav.navigation_pages(nav_container, label=dropdown_label)
 
     nav_group, generated_refs = build_nav_group(
         docs_json_path=docs_json_path,
         details_path=details_path,
         page_paths=page_paths,
     )
-    dropdown["pages"] = canton_protobuf_history.prune_nav_items(
-        pages,
+    target_pages = ledger_api_target_pages(pages, parent_groups=parent_groups)
+    target_pages[:] = canton_protobuf_history.prune_nav_items(
+        target_pages,
         page_refs=generated_refs,
         group_labels={GROUP_LABEL, LEGACY_GROUP_LABEL},
     )
-    target_pages = canton_protobuf_history.ensure_group_path(dropdown["pages"], parent_groups)
     insert_group(target_pages, group=nav_group, after_group=insert_after_group)
     docs_json_path.write_text(json.dumps(docs, indent=2) + "\n", encoding="utf-8")
     print(f"Updated docs navigation: {docs_json_path}")
@@ -698,6 +725,7 @@ def main() -> int:
         docs_json_path=Path(args.docs_json).resolve(),
         dropdown_label=args.nav_dropdown,
     )
+    retitle_package_detail_pages(output_dir=output_dir, page_paths=page_paths)
     print(f"Wrote {len(written_paths)} generated pages under {output_dir}")
     return 0
 

scripts/reference_nav.py

@@ -50,6 +50,39 @@ def load_json(path: Path) -> dict[str, Any]:
     return payload
 
 
+def find_navigation_container(docs: dict[str, Any], *, label: str, docs_json_path: Path) -> dict[str, Any]:
+    navigation = docs.get("navigation")
+    if not isinstance(navigation, dict):
+        raise ValueError(f"docs.json missing navigation object: {docs_json_path}")
+
+    dropdowns = navigation.get("dropdowns")
+    if isinstance(dropdowns, list):
+        dropdown = next(
+            (item for item in dropdowns if isinstance(item, dict) and item.get("dropdown") == label),
+            None,
+        )
+        if dropdown is not None:
+            return dropdown
+
+    products = navigation.get("products")
+    if isinstance(products, list):
+        product = next(
+            (item for item in products if isinstance(item, dict) and item.get("product") == label),
+            None,
+        )
+        if product is not None:
+            return product
+
+    raise ValueError(f"Navigation entry not found in docs.json: {label}")
+
+
+def navigation_pages(container: dict[str, Any], *, label: str) -> list[Any]:
+    pages = container.get("pages")
+    if not isinstance(pages, list):
+        raise ValueError(f"Navigation entry does not expose a pages list: {label}")
+    return pages
+
+
 def _find_group(items: list[Any], label: str) -> dict[str, Any] | None:
     for item in items:
         if isinstance(item, dict) and item.get("group") == label:
@@ -276,24 +309,8 @@ def _absorb_known_item(item: Any, collected: dict[str, dict[str, Any]]) -> bool:
 
 def regroup_ledger_api_nav(*, docs_json_path: Path, dropdown_label: str) -> None:
     docs = load_json(docs_json_path)
-    navigation = docs.get("navigation")
-    if not isinstance(navigation, dict):
-        raise ValueError(f"docs.json missing navigation object: {docs_json_path}")
-
-    dropdowns = navigation.get("dropdowns")
-    if not isinstance(dropdowns, list):
-        raise ValueError(f"docs.json navigation.dropdowns must be a list: {docs_json_path}")
-
-    dropdown = next(
-        (item for item in dropdowns if isinstance(item, dict) and item.get("dropdown") == dropdown_label),
-        None,
-    )
-    if dropdown is None:
-        raise ValueError(f"Dropdown not found in docs.json: {dropdown_label}")
-
-    pages = dropdown.get("pages")
-    if not isinstance(pages, list):
-        raise ValueError(f"Dropdown does not expose a pages list: {dropdown_label}")
+    nav_container = find_navigation_container(docs, label=dropdown_label, docs_json_path=docs_json_path)
+    pages = navigation_pages(nav_container, label=dropdown_label)
 
     known_labels = {
         LEDGER_API_PARENT_GROUP,
@@ -340,5 +357,5 @@ def regroup_ledger_api_nav(*, docs_json_path: Path, dropdown_label: str) -> None
     else:
         remaining.insert(min(insert_at, len(remaining)), parent_group)
 
-    dropdown["pages"] = remaining
+    nav_container["pages"] = remaining
     docs_json_path.write_text(json.dumps(docs, indent=2) + "\n", encoding="utf-8")