Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
14 changes: 11 additions & 3 deletions config/snippet-config/update-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ For repositories with generated snippet JSON, the wrapper runs the required prep

# Workflow architecture

Changes in the external repository snippet source files are being extracted on the external repository, wrapped into an artifact and then being pulled in from this repository into the appropriate folder in the `snippets/external/` folder.
Changes in the external repository snippet source files are being extracted on the external repository, wrapped into an artifact and then being pulled in from this repository into the appropriate folder in the `docs-main/snippets/external/` folder.


## Extract snippet files
Expand Down Expand Up @@ -65,6 +65,14 @@ Line 21 with the path to the `generateOutputDocs.js` script
The snippet extraction script is then called from the GitHub action and extracts snippet files into a temp folder `docs-output`. During the extraction, the files are also transformed: Content is wrapped into a markdown codeblock.
The content of this folder (full extract) is then stored into the [GitHub artifact storage](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflow-artifacts). Afterwards, the `update_snippets` workflow is called on the main repository (this repo), which will pull the snippet files.

Each generated snippet starts with, or for MDX snippets that start with imports places after the import block, a searchable provenance comment:

```mdx
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/example.json" commit="abc123..." snippet="docs-open/target/snippet_json_data/example-0" location="jsonIndex:0-0" -->
```

Use the `source-snippet` prefix, `repo`, `path`, or `commit` fields to map a generated snippet file back to the source repository state that produced it.

## Pulling snippet files

In this repository, the [pull-external-snippets](/.github/workflows/pull-external-snippets.yml) workflow (dispatch name: `update_snippets`) is triggered with the following parameters:
Expand All @@ -74,7 +82,7 @@ In this repository, the [pull-external-snippets](/.github/workflows/pull-externa
* repo-org: External repo org
* repo-version: External repo version

It pulls the external artifact and places the files into `snippets/external/{repo_name}/{repo_version}`. Then, a PR is created (if there are any changed files) towards main on this repository. The PR title contains the repo name, version and the last commit hash (short) of the external repo. If another update is pushed on the external repository, the existing PR is being updated automatically.
It pulls the external artifact and places the files into `docs-main/snippets/external/{repo_name}/{repo_version}`. Then, a PR is created (if there are any changed files) towards main on this repository. The PR title contains the repo name, version and the last commit hash (short) of the external repo. If another update is pushed on the external repository, the existing PR is being updated automatically.

## Full workflow sequence

Expand All @@ -98,7 +106,7 @@ sequenceDiagram

ExtWF->>MainWF: Trigger update_snippets<br/>(artifact-id, run-id, repo-name, repo-org, repo-version)
MainWF->>Artifact: Download external artifact
MainWF->>MainRepo: Copy files to snippets/external/REPO_NAME/REPO_VERSION
MainWF->>MainRepo: Copy files to docs-main/snippets/external/REPO_NAME/REPO_VERSION
MainWF->>MainRepo: Detect file changes
MainWF->>MainRepo: Create/update PR to main<br/>title includes repo/version/short commit hash

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/pack/examples/01-simple-topology/simple-topology.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/pack/examples/01-simple-topology/simple-topology" location="fullFile" -->
```conf
canton {
// user-manual-entry-begin: SimpleSequencerNodeConfig
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/caching-configs.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/caching-configs" location="fullFile" -->
```conf
canton.participants.participant1 {
// tune caching configs of the ledger api server
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/command-service-max-commands-in-flight.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/command-service-max-commands-in-flight" location="fullFile" -->
```conf
canton.participants.participant1.ledger-api.command-service.max-commands-in-flight = 256 // default value

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/crypto-schemes.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/crypto-schemes" location="fullFile" -->
```conf
canton {
participants.participant1 {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/deadlock-detection.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/deadlock-detection" location="fullFile" -->
```conf
canton.monitoring.deadlock-detection.enabled = yes

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/exit-on-fatal-failures.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/exit-on-fatal-failures" location="fullFile" -->
```conf
canton.parameters.exit-on-fatal-failures = no

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/large-in-memory-fan-out.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/large-in-memory-fan-out" location="fullFile" -->
```conf
canton.participants.participant.ledger-api.index-service {
max-transactions-in-memory-fan-out-buffer-size = 10000 // default 1000
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/large-ledger-api-cache.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/large-ledger-api-cache" location="fullFile" -->
```conf
canton.participants.participant.ledger-api.index-service {
max-contract-state-cache-size = 100000 // default 1e4
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/ledger-api-privileged.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/ledger-api-privileged" location="fullFile" -->
```conf
canton {
participants {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/ledger-api-target-scope.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/ledger-api-target-scope" location="fullFile" -->
```conf
canton {
participants {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/ledger-api-user-list.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/ledger-api-user-list" location="fullFile" -->
```conf
canton {
participants {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/log-slow-futures.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/log-slow-futures" location="fullFile" -->
```conf
canton.monitoring.logging.log-slow-futures = yes

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/migrate-and-start.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/migrate-and-start" location="fullFile" -->
```conf
canton.participants.participant1.storage.parameters.migrate-and-start = yes

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/no-fail-fast.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/no-fail-fast" location="fullFile" -->
```conf
canton.participants.participant1.storage.parameters.fail-fast-on-startup = "no"

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/ports-file.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/ports-file" location="fullFile" -->
```conf
canton.parameters.ports-file=ports.json

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/preview-commands.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/preview-commands" location="fullFile" -->
```conf
canton.features.enable-preview-commands=yes

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/sequencer-client-throttling.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/sequencer-client-throttling" location="fullFile" -->
```conf
canton.participants.participant1.sequencer-client.maximum-in-flight-event-batches = 100
canton.mediators.mediator1.sequencer-client.maximum-in-flight-event-batches = 100
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/documentation-snippets/storage-queue-size.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/documentation-snippets/storage-queue-size" location="fullFile" -->
```conf
canton.participants.participant1.storage.config.queueSize = 10000

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/external-ha-sequencers-remote-admin-parsing.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/external-ha-sequencers-remote-admin-parsing" location="fullFile" -->
```conf
canton {
remote-sequencers {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="community/app/src/test/resources/random-node-identifier.conf" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="community/app/src/test/resources/random-node-identifier" location="fullFile" -->
```conf
canton.participants.participant1.init.identity {
type = auto
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/observe/health.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/observe/health-0" location="jsonIndex:0-0" -->
```scala
@ participant1.health.status
res1: NodeStatus[ParticipantStatus] = Participant id: PAR::participant1::12201ff69b1d24edbf0ee2028a304ea702ee8536790dab1a31e7136e6d90ff6d473c
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/observe/health.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/observe/health-1" location="jsonIndex:1-1" -->
```scala
@ health.status
res2: CantonStatus = Status for Sequencer 'sequencer1':
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-0" location="jsonIndex:0-0" -->
```scala
@ val Seq(alice, bob, eve) = Seq("alice", "bob", "eve").map(p => participant1.parties.enable(name = p))
Seq(alice, bob, eve) : Seq[PartyId] = List(alice::12201ff69b1d..., bob::12201ff69b1d..., eve::12201ff69b1d...)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-1" location="jsonIndex:1-1" -->
```scala
@ val user = participant1.ledger_api.users.create(id = "myuser", actAs = Set(alice), readAs = Set(bob), primaryParty = Some(alice), participantAdmin = false, isDeactivated = false, annotations = Map("foo" -> "bar", "description" -> "This is a description"))
user : User = User(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-11" location="jsonIndex:11-11" -->
```scala
@ participant1.ledger_api.users.delete("myotheruser")
```
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-12" location="jsonIndex:12-12" -->
```scala
@ participant1.ledger_api.users.list("myotheruser")
res17: UsersPage = UsersPage(users = Vector(), nextPageToken = "")
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-13" location="jsonIndex:13-13" -->
```scala
@ participant1.ledger_api.users.update("myuser", user => user.copy(isDeactivated = true))
res18: User = User(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-14" location="jsonIndex:14-14" -->
```scala
@ hosting.id.toProtoPrimitive
res1: String = "PAR::participant2::1220a4d7463bd34b2ba3704401b48ab41d8f88cdcbe512fc1ef071aad97fef106161"
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-15" location="jsonIndex:15-15" -->
```scala
@ val secret = client.keys.secret.generate_signing_key("my-party-key", SigningKeyUsage.NamespaceOnly)
secret : SigningPublicKey = SigningPublicKey(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-2" location="jsonIndex:2-2" -->
```scala
@ val updatedUser = participant1.ledger_api.users.update(id = user.id, modifier = user => { user.copy(primaryParty = None, annotations = user.annotations.updated("description", "This is a new description").removed("foo").updated("baz", "bar")) })
updatedUser : User = User(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-20" location="jsonIndex:20-20" -->
```scala
@ hosting.topology.transactions.load_single_from_files(
files = Seq("rootCert.bin", "partyDelegation.bin"),
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-5" location="jsonIndex:5-5" -->
```scala
@ participant1.ledger_api.users.get(user.id)
res9: User = User(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-6" location="jsonIndex:6-6" -->
```scala
@ participant1.ledger_api.users.rights.list(user.id)
res10: UserRights = UserRights(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-7" location="jsonIndex:7-7" -->
```scala
@ participant1.ledger_api.users.rights.grant(id = user.id, actAs = Set(alice, bob), readAs = Set(eve), participantAdmin = true)
res11: UserRights = UserRights(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-8" location="jsonIndex:8-8" -->
```scala
@ participant1.ledger_api.users.rights.revoke(id = user.id, actAs = Set(bob), readAs = Set(alice), participantAdmin = true)
res12: UserRights = UserRights(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/identity_management-9" location="jsonIndex:9-9" -->
```scala
@ participant1.ledger_api.users.rights.list(user.id)
res13: UserRights = UserRights(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages-1" location="jsonIndex:1-1" -->
```scala
@ participant2.dars.list()
res2: Seq[DarDescription] = Vector(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages-10" location="jsonIndex:10-10" -->
```scala
@ val prim = participant2.packages.list(filterName = "daml-prim").head
prim : PackageDescription = PackageDescription(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages-11" location="jsonIndex:11-11" -->
```scala
@ participant2.packages.get_contents(prim.packageId)
res14: PackageDescription.PackageContents = PackageContents(
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<!-- source-snippet repo="canton" path="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages.json" commit="268d267439898d0927bd547f3d7a30ff469b46aa" snippet="docs-open/target/snippet_json_data/participant/howtos/operate/packages/packages-12" location="jsonIndex:12-12" -->
```scala
@ participant2.packages.get_references(prim.packageId)
res15: Seq[DarDescription] = Vector(
Expand Down
Loading