diff --git a/docs-main/docs.json b/docs-main/docs.json index f362deba..e3f631fe 100644 --- a/docs-main/docs.json +++ b/docs-main/docs.json @@ -456,199 +456,174 @@ "group": "gRPC API", "pages": [ { - "group": "Packages", + "group": "v2", "pages": [ { - "group": "v2", + "group": "CommandCompletionService", "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2", - { - "group": "Services", - "pages": [ - { - "group": "CommandCompletionService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandcompletionservice/completionstream" - ] - }, - { - "group": "CommandService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwaitforreassignment", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwaitfortransaction" - ] - }, - { - "group": "CommandSubmissionService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandsubmissionservice/submit", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandsubmissionservice/submitreassignment" - ] - }, - { - "group": "ContractService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/contractservice/getcontract" - ] - }, - { - "group": "EventQueryService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/eventqueryservice/geteventsbycontractid" - ] - }, - { - "group": "PackageService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/getpackage", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/getpackagestatus", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/listpackages", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/listvettedpackages" - ] - }, - { - "group": "StateService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getactivecontracts", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getconnectedsynchronizers", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getlatestprunedoffsets", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getledgerend" - ] - }, - { - "group": "UpdateService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdatebyid", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdatebyoffset", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdates" - ] - }, - { - "group": "VersionService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/versionservice/getledgerapiversion" - ] - } - ] - } + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandcompletionservice/completionstream" ] }, { - "group": "v2.admin", + "group": "CommandService", "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin", - { - "group": "Services", - "pages": [ - { - "group": "CommandInspectionService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/commandinspectionservice/getcommandstatus" - ] - }, - { - "group": "IdentityProviderConfigService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/createidentityproviderconfig", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/deleteidentityproviderconfig", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/getidentityproviderconfig", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/listidentityproviderconfigs", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/updateidentityproviderconfig" - ] - }, - { - "group": "PackageManagementService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/listknownpackages", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/updatevettedpackages", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/uploaddarfile", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/validatedarfile" - ] - }, - { - "group": "ParticipantPruningService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/participantpruningservice/prune" - ] - }, - { - "group": "PartyManagementService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/allocateexternalparty", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/allocateparty", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/generateexternalpartytopology", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/getparticipantid", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/getparties", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/listknownparties", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/updatepartydetails", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/updatepartyidentityproviderid" - ] - }, - { - "group": "UserManagementService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/createuser", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/deleteuser", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/getuser", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/grantuserrights", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/listuserrights", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/listusers", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/revokeuserrights", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/updateuser", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/updateuseridentityproviderid" - ] - } - ] - } + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwaitforreassignment", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwaitfortransaction" ] }, { - "group": "v2.interactive", + "group": "CommandSubmissionService", "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive", - { - "group": "Services", - "pages": [ - { - "group": "InteractiveSubmissionService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmission", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmissionandwait", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmissionandwaitfortransaction", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/getpreferredpackages", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/getpreferredpackageversion", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/preparesubmission" - ] - } - ] - } + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandsubmissionservice/submit", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandsubmissionservice/submitreassignment" ] }, { - "group": "v2.interactive.transaction.v1", + "group": "ContractService", "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1" + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/contractservice/getcontract" ] }, { - "group": "v2.testing", + "group": "EventQueryService", "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing", - { - "group": "Services", - "pages": [ - { - "group": "TimeService", - "pages": [ - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing/timeservice/gettime", - "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing/timeservice/settime" - ] - } - ] - } + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/eventqueryservice/geteventsbycontractid" ] - } + }, + { + "group": "PackageService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/getpackage", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/getpackagestatus", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/listpackages", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/packageservice/listvettedpackages" + ] + }, + { + "group": "StateService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getactivecontracts", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getconnectedsynchronizers", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getlatestprunedoffsets", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/stateservice/getledgerend" + ] + }, + { + "group": "UpdateService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdatebyid", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdatebyoffset", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/updateservice/getupdates" + ] + }, + { + "group": "VersionService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/versionservice/getledgerapiversion" + ] + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2" + ] + }, + { + "group": "v2.admin", + "pages": [ + { + "group": "CommandInspectionService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/commandinspectionservice/getcommandstatus" + ] + }, + { + "group": "IdentityProviderConfigService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/createidentityproviderconfig", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/deleteidentityproviderconfig", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/getidentityproviderconfig", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/listidentityproviderconfigs", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/identityproviderconfigservice/updateidentityproviderconfig" + ] + }, + { + "group": "PackageManagementService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/listknownpackages", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/updatevettedpackages", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/uploaddarfile", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/packagemanagementservice/validatedarfile" + ] + }, + { + "group": "ParticipantPruningService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/participantpruningservice/prune" + ] + }, + { + "group": "PartyManagementService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/allocateexternalparty", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/allocateparty", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/generateexternalpartytopology", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/getparticipantid", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/getparties", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/listknownparties", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/updatepartydetails", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/partymanagementservice/updatepartyidentityproviderid" + ] + }, + { + "group": "UserManagementService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/createuser", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/deleteuser", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/getuser", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/grantuserrights", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/listuserrights", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/listusers", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/revokeuserrights", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/updateuser", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin/usermanagementservice/updateuseridentityproviderid" + ] + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin" + ] + }, + { + "group": "v2.interactive", + "pages": [ + { + "group": "InteractiveSubmissionService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmission", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmissionandwait", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/executesubmissionandwaitfortransaction", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/getpreferredpackages", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/getpreferredpackageversion", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive/interactivesubmissionservice/preparesubmission" + ] + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive" + ] + }, + { + "group": "v2.interactive.transaction.v1", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1" + ] + }, + { + "group": "v2.testing", + "pages": [ + { + "group": "TimeService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing/timeservice/gettime", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing/timeservice/settime" + ] + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing" ] }, "reference/grpc-ledger-api-reference/details" diff --git a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin.mdx b/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin.mdx index 5e6e1da8..ab2f0298 100644 --- a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-admin.mdx +++ b/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."

Protobuf Package

-

v2.admin

+

Details and history

6 services, 28 endpoints, 78 messages, 3 enums

diff --git a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1.mdx b/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1.mdx index 5675a6ea..6c7c5774 100644 --- a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive-transaction-v1.mdx +++ b/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

Protobuf Package

-

v2.interactive.transaction.v1

+

Details and history

0 services, 0 endpoints, 5 messages

diff --git a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive.mdx b/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive.mdx index bfad6f5a..9c12f1f6 100644 --- a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-interactive.mdx +++ b/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."

Protobuf Package

-

v2.interactive

+

Details and history

1 services, 6 endpoints, 28 messages, 1 enums

diff --git a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing.mdx b/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing.mdx index c4a006a5..43ff868a 100644 --- a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2-testing.mdx +++ b/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."

Protobuf Package

-

v2.testing

+

Details and history

1 services, 2 endpoints, 3 messages

diff --git a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2.mdx b/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2.mdx index 4a22ff83..58bf3e54 100644 --- a/docs-main/reference/grpc-ledger-api-reference/com-daml-ledger-api-v2.mdx +++ b/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."

Protobuf Package

-

v2

+

Details and history

9 services, 20 endpoints, 115 messages, 8 enums

diff --git a/scripts/generate_grpc_ledger_api_reference.py b/scripts/generate_grpc_ledger_api_reference.py index 05fec4c8..1738f781 100644 --- a/scripts/generate_grpc_ledger_api_reference.py +++ b/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"

{html_text(title)}

", f"

{DETAILS_LABEL}

"), + ], + ) + + 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 diff --git a/scripts/reference_nav.py b/scripts/reference_nav.py index 936e8d10..4ba7998e 100644 --- a/scripts/reference_nav.py +++ b/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") diff --git a/tests/test_grpc_ledger_api_nav.py b/tests/test_grpc_ledger_api_nav.py new file mode 100644 index 00000000..c85f15c8 --- /dev/null +++ b/tests/test_grpc_ledger_api_nav.py @@ -0,0 +1,242 @@ +from __future__ import annotations + +import json +import importlib.util +import sys +import os +import tempfile +import unittest +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parents[1] + + +def load_script_module(): + os.environ.setdefault("DIGITAL_ASSET_DOCS_DIRENV", "1") + scripts_dir = str(REPO_ROOT / "scripts") + if scripts_dir not in sys.path: + sys.path.insert(0, scripts_dir) + spec = importlib.util.spec_from_file_location( + "generate_grpc_ledger_api_reference", + REPO_ROOT / "scripts" / "generate_grpc_ledger_api_reference.py", + ) + assert spec is not None + assert spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules["generate_grpc_ledger_api_reference"] = module + spec.loader.exec_module(module) + return module + + +generate_grpc_ledger_api_reference = load_script_module() +DETAILS_LABEL = generate_grpc_ledger_api_reference.DETAILS_LABEL + + +class GrpcLedgerApiNavTests(unittest.TestCase): + def setUp(self) -> None: + self.temp_dir = tempfile.TemporaryDirectory() + self.root = Path(self.temp_dir.name) + self.docs_json = self.root / "docs-main" / "docs.json" + self.output_dir = self.root / "docs-main" / "reference" / "grpc-ledger-api-reference" + self.output_dir.mkdir(parents=True) + self.docs_json.parent.mkdir(parents=True, exist_ok=True) + self.docs_json.write_text(json.dumps({"navigation": {"dropdowns": []}}) + "\n", encoding="utf-8") + + def tearDown(self) -> None: + self.temp_dir.cleanup() + + def _write_page(self, relative_path: str, title: str, *, service: str | None = None) -> Path: + path = self.output_dir / relative_path + path.parent.mkdir(parents=True, exist_ok=True) + service_markup = "" + if service: + service_markup = f"\n
Service
\n
{service}
\n" + path.write_text( + f'---\ntitle: "{title}"\n---\n\n

{title}

\n{service_markup}', + encoding="utf-8", + ) + return path + + def test_nav_flattens_packages_and_services_with_package_details_last(self) -> None: + details_page = self._write_page("details.mdx", DETAILS_LABEL) + package_page = self._write_page("com-daml-ledger-api-v2.mdx", "v2") + operation_page = self._write_page( + "com-daml-ledger-api-v2/commandservice/submitandwait.mdx", + "SubmitAndWait", + service="CommandService", + ) + + nav_group, refs = generate_grpc_ledger_api_reference.build_nav_group( + docs_json_path=self.docs_json, + details_path=details_page, + page_paths=[package_page, operation_page], + ) + + self.assertEqual(nav_group["group"], "gRPC API") + self.assertEqual( + nav_group["pages"], + [ + { + "group": "v2", + "pages": [ + { + "group": "CommandService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait" + ], + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2", + ], + }, + "reference/grpc-ledger-api-reference/details", + ], + ) + self.assertNotIn("Packages", json.dumps(nav_group)) + self.assertNotIn("Services", json.dumps(nav_group)) + self.assertEqual( + refs, + { + "reference/grpc-ledger-api-reference/details", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2", + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait", + }, + ) + + def test_package_pages_are_retitled_after_nav_labels_are_built(self) -> None: + package_page = self._write_page("com-daml-ledger-api-v2.mdx", "v2") + operation_page = self._write_page( + "com-daml-ledger-api-v2/commandservice/submitandwait.mdx", + "SubmitAndWait", + service="CommandService", + ) + + generate_grpc_ledger_api_reference.retitle_package_detail_pages( + output_dir=self.output_dir, + page_paths=[package_page, operation_page], + ) + + package_text = package_page.read_text(encoding="utf-8") + operation_text = operation_page.read_text(encoding="utf-8") + self.assertIn(f'title: "{DETAILS_LABEL}"', package_text) + self.assertIn(f'

{DETAILS_LABEL}

', package_text) + self.assertIn('title: "SubmitAndWait"', operation_text) + + def test_update_docs_navigation_supports_products_navigation(self) -> None: + details_page = self._write_page("details.mdx", DETAILS_LABEL) + package_page = self._write_page("com-daml-ledger-api-v2.mdx", "v2") + operation_page = self._write_page( + "com-daml-ledger-api-v2/commandservice/submitandwait.mdx", + "SubmitAndWait", + service="CommandService", + ) + self.docs_json.write_text( + json.dumps( + { + "navigation": { + "products": [ + { + "product": "API Reference", + "pages": [ + "api-reference", + { + "group": "Ledger API", + "pages": [ + "appdev/reference/pqs-sql-reference", + { + "group": "gRPC API", + "pages": [ + { + "group": "Packages", + "pages": [ + { + "group": "v2", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2", + { + "group": "Services", + "pages": [ + { + "group": "CommandService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait" + ], + } + ], + }, + ], + } + ], + }, + "reference/grpc-ledger-api-reference/details", + ], + }, + ], + }, + { + "group": "Admin API", + "pages": [ + { + "group": "gRPC API", + "pages": [ + { + "group": "Packages", + "pages": [ + "reference/admin-api/protobuf/packages/com-digitalasset-canton-admin" + ], + } + ], + } + ], + }, + ], + } + ] + } + } + ) + + "\n", + encoding="utf-8", + ) + + generate_grpc_ledger_api_reference.update_docs_navigation( + docs_json_path=self.docs_json, + dropdown_label="API Reference", + parent_groups=[], + insert_after_group=None, + details_path=details_page, + page_paths=[package_page, operation_page], + ) + generate_grpc_ledger_api_reference.reference_nav.regroup_ledger_api_nav( + docs_json_path=self.docs_json, + dropdown_label="API Reference", + ) + + docs = json.loads(self.docs_json.read_text(encoding="utf-8")) + product_pages = docs["navigation"]["products"][0]["pages"] + ledger_api = next(item for item in product_pages if isinstance(item, dict) and item.get("group") == "Ledger API") + grpc_api = next(item for item in ledger_api["pages"] if isinstance(item, dict) and item.get("group") == "gRPC API") + admin_api = next(item for item in product_pages if isinstance(item, dict) and item.get("group") == "Admin API") + admin_grpc_api = next( + item for item in admin_api["pages"] if isinstance(item, dict) and item.get("group") == "gRPC API" + ) + self.assertEqual( + grpc_api["pages"], + [ + { + "group": "v2", + "pages": [ + { + "group": "CommandService", + "pages": [ + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2/commandservice/submitandwait" + ], + }, + "reference/grpc-ledger-api-reference/com-daml-ledger-api-v2", + ], + }, + "reference/grpc-ledger-api-reference/details", + ], + ) + self.assertNotIn("Packages", json.dumps(grpc_api)) + self.assertNotIn("Services", json.dumps(grpc_api)) + self.assertIn("reference/admin-api/protobuf/packages/com-digitalasset-canton-admin", json.dumps(admin_grpc_api))