Skip to content

Update for README for better Builder Readability: Issue #703 #731

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jatinp26 wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Update for README for better Builder Readability: Issue #703 #731

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
410d88b
added feedback section in guide
Jatinp26 May 13, 2026
5389c5c
Merge branch 'canton-network:main' into main
Jatinp26 May 26, 2026
0228038
Merge branch 'canton-network:main' into main
Jatinp26 Jun 10, 2026
ac88a6f
Update Readme: Issue #703
Jatinp26 Jun 10, 2026
e455672
Merge branch 'canton-network:main' into main
Jatinp26 Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 46 additions & 49 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
Copyright (c) 2026 Canton Network. All rights reserved.
SPDX-License-Identifier: Apache-2.0 AND CC-BY-4.0

docs
====
# Canton Network Docs

This repo manages the contents of the [docs.canton.network](https://docs.canton.network) website.

Copyright (c) 2026 Canton Network. All rights reserved.
SPDX-License-Identifier: Apache-2.0 AND CC-BY-4.0

## Local Development

### Prerequisites
Expand All @@ -29,21 +28,41 @@ cd docs-main && mintlify dev

The site will be available at http://localhost:3000.

### Useful commands
### Check for broken links

```bash
# Check for broken links
mintlify broken-links
```

## License
## Provide Feedback on a Docs Page

This repository uses a dual-license model:
![suggest edits and raise issues](images/readme/readme-edits-issues.png)

- **Documentation prose** (`.mdx` files, text content): [Creative Commons Attribution 4.0 International (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/) — see [LICENSE-DOCS](LICENSE-DOCS)
- **Code snippets and configuration** (embedded code examples, scripts, JSON config): [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) — see [LICENSE](LICENSE)
Every page on docs.canton.network has two feedback buttons in the footer:
- `Suggest edits`
- `Raise issue`

### Suggest edits:
Use this to propose a direct change to the page, fix a typo, update a code sample, improve wording, etc.

**How it works:**

- Click “Suggest edits” in the footer of any page.
- GitHub opens the source file for that exact page.
- Fork the repo, make your edits, and open a Pull Request.
- Canton docs team reviews and merges accepted changes if all checks out.

### Run all generated reference docs
### Raise Issue:
Use this to report a problem or request new content without editing the source yourself.

**How it works:**

- Click “Raise Issue” in the footer of any page.
- A GitHub Issue opens *Pre-filled* with the Path of the page you were on.
- 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`:

Expand Down Expand Up @@ -76,7 +95,7 @@ By default this writes:

For a pinned refresh, pass `--canton-ref v3.5.1`.

### Generate the Version Compatibility Dashboard
## 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.

Expand Down Expand Up @@ -117,7 +136,7 @@ Source rules:
| `Release Notes` | Link to the observed Splice release. |
| `Primary Scan API` | Static canonical `scan.sv-1...` endpoint for each network. |

### Generate external snippets
## 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/`.

Expand All @@ -126,7 +145,7 @@ npm run generate:external-snippets -- --list
npm run generate:external-snippets -- canton --source-dir ../canton
```

### Generate the JSON API reference
## 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:
Expand All @@ -148,7 +167,7 @@ By default this writes:

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
## 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.
Expand All @@ -172,7 +191,7 @@ By default this writes:

The generated page is placed directly under the top-level `API Reference` dropdown in `docs-main/docs.json`.

### Generate the Ledger bindings API reference
## 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.
Expand All @@ -197,7 +216,7 @@ By default this writes:

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
## 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.
Expand All @@ -221,7 +240,7 @@ By default this writes:

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
## 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-<version>.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.
Expand All @@ -245,7 +264,7 @@ By default this writes:

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
## 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`.
Expand All @@ -269,7 +288,7 @@ By default this writes:

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
## 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.
Expand All @@ -293,7 +312,7 @@ By default this writes:

The generator also adds that page under the top-level `API Reference` dropdown as `TypeScript -> @daml/types`.

### Generate the Wallet Gateway JSON-RPC reference
## 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.
Expand All @@ -310,7 +329,7 @@ or:
npm run generate:wallet-gateway-openrpc-reference
```

### Generate the Splice Mintlify OpenAPI specs
## 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`.

Expand All @@ -333,31 +352,9 @@ By default this writes:

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

## Provide Feedback on a 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`

### Suggest edits:
Use this to propose a direct change to the page, fix a typo, update a code sample, improve wording, etc.

**How it works:**

- Click “Suggest edits” in the footer of any page.
- GitHub opens the source file for that exact page.
- Fork the repo, make your edits, and open a Pull Request.
- Canton docs team reviews and merges accepted changes if all checks out.

### Raise Issue:
Use this to report a problem or request new content without editing the source yourself.

**How it works:**
This repository uses a dual-license model:

- Click “Raise Issue” in the footer of any page.
- A GitHub Issue opens *Pre-filled* with the Path of the page you were on.
- Describe in detail what's wrong or missing along with the source of information to verify and submit.
- The team reviews it and responds.
- **Documentation prose** (`.mdx` files, text content): [Creative Commons Attribution 4.0 International (CC-BY-4.0)](https://creativecommons.org/licenses/by/4.0/) — see [LICENSE-DOCS](LICENSE-DOCS)
- **Code snippets and configuration** (embedded code examples, scripts, JSON config): [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) — see [LICENSE](LICENSE)