diff --git a/README.md b/README.md index b77c774a7..6ed83556b 100644 --- a/README.md +++ b/README.md @@ -5,43 +5,15 @@ This repo manages the contents of the [docs.canton.network](https://docs.canton. Copyright (c) 2026 Canton Network. All rights reserved. SPDX-License-Identifier: Apache-2.0 AND CC-BY-4.0 -## Local Development - -### Prerequisites - -Either: - -- [`direnv`](https://direnv.net/) -- [`nix`](https://nixos.org/download/) - -OR: - -- [Node.js 24](https://nodejs.org/en/download) (note that `mintlify` is not currently compatible with Node.js 26) -- [Python 3.14](https://www.python.org/downloads/) if you are running any of the machinery for syncing snippets or updating generated docs - -### Running the dev server - -```bash -direnv allow -cd docs-main && mintlify dev -``` - -The site will be available at http://localhost:3000. - -### Check for broken links - -```bash -mintlify broken-links -``` ## Provide Feedback on a Docs Page -![suggest edits and raise issues](images/readme/readme-edits-issues.png) - Every page on docs.canton.network has two feedback buttons in the footer: - `Suggest edits` - `Raise issue` +image + ### Suggest edits: Use this to propose a direct change to the page, fix a typo, update a code sample, improve wording, etc. @@ -62,296 +34,47 @@ Use this to report a problem or request new content without editing the source y - Describe in detail what's wrong or missing along with the source of information to verify and submit. - The team reviews it and responds. -## Run all generated reference docs - -Load the repo's `direnv` / `nix` shell first, then rerun all generated reference-doc wrappers in one command. The wrappers also re-exec through the docs repo shell themselves, so they do not pick up a local `x2mdx` checkout from ambient `PATH`: -```bash -direnv allow -python3 scripts/generate_all_reference_docs.py -``` +## Local Development -Use `--dry-run` to print the exact per-step commands without executing them. +### Prerequisites -### Generate the Canton Metrics reference +Either: -The Canton Metrics page is generated from the Canton release docs build rather than from protobuf files. The generator resolves the latest `DACH-NY/canton` GitHub release tag, checks out that Canton source tag under `.internal/cache/canton-metrics-reference/`, runs Canton's release bundle plus generated-include tasks, resolves the metrics RST template with the generated metric includes, converts it to MDX, and records the source release in the generated page comment. +- [`direnv`](https://direnv.net/) +- [`nix`](https://nixos.org/download/) -Run: +OR: -```bash -python3 scripts/generate_canton_metrics_reference.py -``` +- [Node.js 24](https://nodejs.org/en/download) (note that `mintlify` is not currently compatible with Node.js 26) +- [Python 3.14](https://www.python.org/downloads/) if you are running any of the machinery for syncing snippets or updating generated docs -or: +### Running the dev server ```bash -npm run generate:canton-metrics-reference +direnv allow +cd docs-main && mintlify dev ``` -By default this writes: - -- `docs-main/global-synchronizer/reference/canton-metrics.mdx` - -For a pinned refresh, pass `--canton-ref v3.5.1`. - -## Generate the Version Compatibility Dashboard - -The version dashboard generator collects the public sources that are safe to automate, preserves the fields that still need a manual or owner-approved source, rewrites the dashboard config, and regenerates the published MDX snippet consumed by the version dashboard page. - -Run: - -```bash -python3 scripts/generate_network_component_versions.py -``` +The site will be available at http://localhost:3000. -or: +### Check for broken links ```bash -npm run generate:version-compatibility-dashboard +mintlify broken-links ``` -By default this writes: - -- `config/repo-version-config.json` -- `docs-main/snippets/generated/version-dashboard-data.mdx` - -Use `--dry-run` to inspect the generated config without writing files. - -Source rules: - -| Dashboard entry | Sourcing rule | -| --- | --- | -| `Splice` | Read from the network `/info` endpoint: MainNet `https://docs.global.canton.network.sync.global/info`, TestNet `https://docs.test.global.canton.network.sync.global/info`, DevNet `https://docs.dev.global.canton.network.sync.global/info`. Cross-check against the same network's `/index.html` Docker image tag and Helm chart version. | -| `Canton` | Read the network Splice version from `/info`, derive the matching `canton-network/splice` release-line branch, then read `version` from `nix/canton-sources.json`. The config key is still `damlSdk` for compatibility with the existing dashboard component. | -| `Daml SDK installer` | Do not use legacy `https://get.daml.com/`; that is the old 2.x Daml assistant path. For Daml 3 / DPM, install DPM with `curl https://get.digitalasset.com/install/install.sh | sh`, then use `dpm install latest`. The latest stable SDK version is exposed at `https://get.digitalasset.com/install/latest`. | -| `PQS` | Read the latest stable semver tag from the public Artifact Registry image `europe-docker.pkg.dev/da-images/public/docker/participant-query-store`. | -| `Token Standard` | Read from the npm `latest` dist-tag for `@canton-network/core-token-standard`. | -| `Wallet SDK` | Read from the npm `latest` dist-tag for `@canton-network/wallet-sdk`. | -| `dApp SDK` | Read from the npm `latest` dist-tag for `@canton-network/dapp-sdk`. | -| `Wallet Gateway` | Read the latest stable `@canton-network/wallet-gateway-remote` release from `hyperledger-labs/splice-wallet-kernel` GitHub releases. | -| `Min Protocol Version` | Keep as manual/fallback until a public live source is available. | -| `Migration ID` | Read from `synchronizer.active.migration_id` on the network's `/info` endpoint and validate against `sv.migration_id`. | -| `Splice DAR Versions` | Read the latest stable package rows for `splice-amulet`, `splice-wallet`, and `splice-dso-governance` from the observed Splice release-line `daml/dars.lock`. | -| `Release Notes` | Link to the observed Splice release. | -| `Primary Scan API` | Static canonical `scan.sv-1...` endpoint for each network. | - ## Generate external snippets External snippet extraction from source repositories is documented in [config/snippet-config/update-workflows.md](config/snippet-config/update-workflows.md). Use that workflow when updating snippet configs under `config/snippet-config/` or regenerating checked-in snippets under `docs-main/snippets/external/`. +Run this whenever you add, remove, or update a snippet source in `config/snippet-config/`, or when you need to pull in changes from an upstream repo (such as Canton or Splice) that are referenced by existing snippets. + ```bash npm run generate:external-snippets -- --list npm run generate:external-snippets -- canton --source-dir ../canton ``` -## Generate the JSON API reference - -This repo includes a checked-in source config for the Ledger API OpenAPI bundle inputs under `config/x2mdx/ledger-api/source-artifacts.json`. -The generator script refreshes the latest configured `openapi.yaml` from the Canton release bundle into the docs tree and rewires `docs-main/docs.json` so Mintlify renders the JSON API reference natively: - -```bash -python3 scripts/generate_json_api_reference.py -``` - -or: - -```bash -npm run generate:json-api-reference -``` - -By default this writes: - -- `docs-main/openapi/json-ledger-api/openapi.yaml` -- `docs-main/docs.json` - -The generated nav is published under `API Reference -> Ledger API -> OpenAPI`, using Mintlify's native generated endpoint pages under `reference/json-api-reference`. The legacy checked-in MDX page at `docs-main/reference/json-api-reference.mdx` is removed by the generator. - -## Generate the JSON API AsyncAPI reference - -This repo also includes a checked-in source config for the Ledger API AsyncAPI bundle inputs under `config/x2mdx/ledger-api-asyncapi/source-artifacts.json`. -The generator script downloads the configured Canton release bundles, extracts `asyncapi.yaml` into `.internal/cache/x2mdx/ledger-api-asyncapi/`, writes a local x2mdx manifest into `.internal/generated/x2mdx/ledger-api-asyncapi/manifest.json`, and then renders the MDX page through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_json_api_asyncapi_reference.py -``` - -or: - -```bash -npm run generate:json-api-asyncapi-reference -``` - -By default this writes: - -- `docs-main/reference/json-api-asyncapi-reference.mdx` -- `docs-main/docs.json` - -The generated page is placed directly under the top-level `API Reference` dropdown in `docs-main/docs.json`. - -## Generate the Ledger bindings API reference - -This repo also includes a checked-in source config for the published Java bindings Javadoc jars at `config/x2mdx/ledger-bindings/source-artifacts.json`. -The generator script downloads those jars into `.internal/cache/x2mdx/ledger-bindings/`, writes a local x2mdx manifest into `.internal/generated/x2mdx/ledger-bindings/manifest.json`, and then renders the MDX pages through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_ledger_bindings_api_reference.py -``` - -or: - -```bash -npm run generate:ledger-bindings-api-reference -``` - -By default this writes: - -- `docs-main/reference/java-bindings.mdx` -- `docs-main/reference/java/` -- `docs-main/docs.json` - -The generated nav is added under the top-level `API Reference` dropdown as `Java Bindings -> Javadocs`, with each nested group populated directly from the generated Java package pages. - -## Generate the Daml Standard Library reference - -This repo also includes a checked-in source config for versioned Daml Standard Library docs JSON generation at `config/x2mdx/daml-standard-library/source-artifacts.json`. -The generator script uses local SDK artifacts via `dpm` or `daml` to build cached docs JSON snapshots under `.internal/cache/x2mdx/daml-standard-library/`, writes a local x2mdx manifest into `.internal/generated/x2mdx/daml-standard-library/manifest.json`, and then renders MDX pages through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_daml_standard_library_reference.py -``` - -or: - -```bash -npm run generate:daml-standard-library-reference -``` - -By default this writes: - -- `docs-main/appdev/reference/daml-standard-library/` -- `docs-main/docs.json` - -The generated nav is added under the top-level `API Reference` dropdown as `Daml Standard Library`, with the overview page listed first and the generated module pages grouped under a nested `Modules` foldout. - -## Generate the Canton protobuf history reference - -This repo also includes a checked-in source config for Canton release-bundle protobuf inputs at `config/x2mdx/protobuf-history/source-artifacts.json`. -The generator script discovers stable Canton versions from the source repo tags, downloads the matching `canton-open-source-.tar.gz` bundles from `canton.io/releases`, extracts the published `protobuf/` tree under `.internal/cache/x2mdx/protobuf-history/`, compiles local descriptor images with `grpc_tools.protoc`, writes a local x2mdx manifest into `.internal/generated/x2mdx/protobuf-history/manifest.json`, and then renders MDX pages through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_canton_protobuf_history.py -``` - -or: - -```bash -npm run generate:canton-protobuf-history -``` - -By default this writes: - -- `docs-main/appdev/reference/protobuf-history/` -- `docs-main/docs.json` - -The generated nav is added under the top-level `API Reference` dropdown as `Canton Protobuf History`, with only the overview page listed in nav. The per-endpoint pages are generated and linked from the overview page but left unlisted. - -## Generate the gRPC Ledger API reference - -This repo also includes a checked-in source config for the Ledger API gRPC protobuf surface at `config/x2mdx/grpc-ledger-api-reference/source-artifacts.json`. -The generator script reuses the published Canton release-bundle protobuf acquisition flow, filters the resulting protobuf report to `com.daml.ledger.api.v2*`, and writes a dedicated Ledger API-only MDX surface without modifying `x2mdx`. - -Run: - -```bash -python3 scripts/generate_grpc_ledger_api_reference.py -``` - -or: - -```bash -npm run generate:grpc-ledger-api-reference -``` - -By default this writes: - -- `docs-main/reference/grpc-ledger-api-reference/` -- `docs-main/docs.json` - -The generated nav is added under the top-level `Reference` dropdown as `gRPC Ledger API Reference`, with the overview page first and the generated package pages grouped under a nested `Packages` foldout. - -## Generate the TypeScript bindings reference - -This repo also includes a checked-in source config for published `@daml/types` npm artifacts at `config/x2mdx/typescript-bindings/source-artifacts.json`. -The generator script downloads the configured tarballs into `.internal/cache/x2mdx/typescript-bindings/`, installs local package dependencies, renders TypeDoc JSON into `.internal/generated/x2mdx/typescript-bindings/`, writes a local x2mdx manifest, and then rewrites the checked-in Mintlify page through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_typescript_bindings_reference.py -``` - -or: - -```bash -npm run generate:typescript-bindings-reference -``` - -By default this writes: - -- `docs-main/reference/typescript.mdx` -- `docs-main/docs.json` - -The generator also adds that page under the top-level `API Reference` dropdown as `TypeScript -> @daml/types`. - -## Generate the Wallet Gateway JSON-RPC reference - -This repo also includes a checked-in source config for versioned Wallet Gateway OpenRPC specs from `hyperledger-labs/splice-wallet-kernel` at `config/x2mdx/wallet-gateway-openrpc/source-artifacts.json`. -The generator script discovers versions from GitHub releases filtered to the `@canton-network/wallet-gateway-remote@` release stream, clones or fetches a cached bare repo under `.internal/cache/x2mdx/wallet-gateway-openrpc/`, materializes local versioned OpenRPC JSON files from the matching tag snapshots, writes a local x2mdx manifest into `.internal/generated/x2mdx/wallet-gateway-openrpc/manifest.json`, and then renders MDX pages through the docs repo `direnv` / `nix` shell. - -Run: - -```bash -python3 scripts/generate_wallet_gateway_openrpc_reference.py -``` - -or: - -```bash -npm run generate:wallet-gateway-openrpc-reference -``` - -## Generate the Splice Mintlify OpenAPI specs - -This repo also includes a dedicated wrapper that fetches the configured Splice OpenAPI specs from published decentralized-canton-sync `*_openapi.tar.gz` release bundles and writes the managed source files under `docs-main/openapi/splice/`, so Mintlify can render them natively. The wrapper only updates `docs-main/docs.json` for specs listed in `config/mintlify-openapi/splice-openapi/source-artifacts.json` under `enabled_nav_specs`. - -Run: - -```bash -python3 scripts/generate_splice_mintlify_openapi.py -``` - -or: - -```bash -npm run generate:splice-mintlify-openapi -``` - -By default this writes: - -- `docs-main/openapi/splice/` -- `docs-main/docs.json` only when one or more specs are enabled in `enabled_nav_specs` - -Enabled specs are added under the top-level `API Reference` dropdown as `Splice APIs`, with Mintlify-rendered OpenAPI entries grouped under `Scan APIs`, `Validator APIs`, and `Token Standard APIs`. - ## License This repository uses a dual-license model: diff --git a/docs-main/api-reference.mdx b/docs-main/api-reference.mdx index 7c43c74ef..a3e0a636b 100644 --- a/docs-main/api-reference.mdx +++ b/docs-main/api-reference.mdx @@ -31,7 +31,7 @@ The API Reference covers every programmatic interface to Canton - review endpoin Versioned OpenRPC reference - use this to integrate wallets and dApps with the Splice Wallet Gateway. - + Developing with Canton Network's OpenAPI endpoints for: Canton Coin data, name service, token standard, and more.