From 410d88babf4ad07d5e4875f86d98a10bcde9ff14 Mon Sep 17 00:00:00 2001 From: Jatinp26 Date: Wed, 13 May 2026 11:00:39 +0530 Subject: [PATCH 1/2] added feedback section in guide --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index cedc8742e..27265bbc4 100644 --- a/README.md +++ b/README.md @@ -278,3 +278,30 @@ By default this writes: - `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`. + + +## Provide Feedback on a Page + +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:** + +- 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. From ac88a6f6707ecfaebee952e9ae7754a6f05e377b Mon Sep 17 00:00:00 2001 From: Jatinp26 Date: Wed, 10 Jun 2026 16:14:04 -0400 Subject: [PATCH 2/2] Update Readme: Issue #703 --- README.md | 95 +++++++++++++++++++++++++++---------------------------- 1 file changed, 46 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index d9a390316..b77c774a7 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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`: @@ -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. @@ -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/`. @@ -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: @@ -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. @@ -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. @@ -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. @@ -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-.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. @@ -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`. @@ -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. @@ -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. @@ -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`. @@ -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)