Adding concept pages with bullet points

.github/workflows/pre-release.yml

@@ -12,7 +12,7 @@ on:
         required: false
         type: string
       sdkJavaVersion:
-        description: 'sdk-java version (without prepending v).'
+        description: "sdk-java version (without prepending v)."
         required: false
         type: string
       tourVersion:
@@ -87,13 +87,41 @@ jobs:
           field: JAVA_SDK_VERSION
           value: ${{ inputs.sdkJavaVersion }}
 
-      - name: Update restate.config.json with new tour version (TypeScript + Java)
-        uses: jossef/[email protected]
-        if: ${{ inputs.tourVersion != '' }}
+      # Upgrade TS code snippets if new version is provided
+      - name: Upgrade TS Restate SDK
+        if: github.event.inputs.sdkTypescriptVersion != ''
+        run: npm --prefix code_snippets/ts install @restatedev/restate-sdk@^${{ inputs.sdkTypescriptVersion }}
+
+      # Test if TS code snippets compile and build
+      - name: Compile TypeScript code snippets
+        run: npm install --prefix code_snippets/ts && npm run build --prefix code_snippets/ts
+
+      # Upgrade TS gRPC code snippets if new version is provided
+      - name: Upgrade TS Restate SDK for gRPC code snippets
+        if: github.event.inputs.sdkTypescriptVersion != ''
+        run: npm --prefix code_snippets/ts-grpc install @restatedev/restate-sdk@^${{ inputs.sdkTypescriptVersion }}
+
+      # Test if TS gRPC code snippets compile and build
+      - name: Compile TypeScript gRPC code snippets
+        run: npm install --prefix code_snippets/ts-grpc && npm run proto --prefix code_snippets/ts-grpc && npm run build --prefix code_snippets/ts-grpc
+
+      # Setup Java
+      - uses: actions/setup-java@v3
         with:
-          file: restate.config.json
-          field: TOUR_VERSION
-          value: ${{ inputs.tourVersion }}
+          distribution: 'temurin'
+          java-version: '17'
+
+      # Upgrade Java code snippets if new version is provided
+      - name: Find and replace restateVersion in build.gradle.kts for Java code snippets
+        if: github.event.inputs.sdkJavaVersion != ''
+        run: sed -i 's/val restateVersion = "[0-9A-Z.-]*"/val restateVersion = "${{ inputs.sdkJavaVersion }}"/' code_snippets/java/build.gradle.kts
+
+      # Check Java code snippets
+      - name: Test Java code snippets
+        uses: gradle/gradle-build-action@v2
+        with:
+          arguments: check
+          build-root-directory: code_snippets/java
 
       - name: Create Pull Request
         uses: peter-evans/create-pull-request@v5

.github/workflows/test-build.yml

@@ -26,3 +26,43 @@ jobs:
         run: yarn install --frozen-lockfile
       - name: Test build website
         run: yarn build
+
+
+      # Test TypeScript code snippets
+      - name: Compile TypeScript code snippets
+        run: npm install --prefix code_snippets/ts && npm run build --prefix code_snippets/ts
+
+      - name: Check if TypeScript code snippets build is successful
+        run: |
+          if [ -d "code_snippets/ts/dist" ]; then
+          echo "TypeScript compilation successful"
+          else
+          echo "TypeScript compilation failed"
+          exit 1
+          fi
+
+      # Test TypeScript gRPC code snippets
+      - name: Compile TypeScript gRPC code snippets
+        run: npm install --prefix code_snippets/ts-grpc && npm run proto --prefix code_snippets/ts-grpc && npm run build --prefix code_snippets/ts-grpc
+
+      - name: Check if TypeScript gRPC code snippets build is successful
+        run: |
+          if [ -d "code_snippets/ts-grpc/dist" ]; then
+          echo "TypeScript gRPC code snippets compilation successful"
+          else
+          echo "TypeScript gRPC code snippets compilation failed"
+          exit 1
+          fi
+
+      # Setup Java
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      # Check Java code snippets
+      - name: Test Java code snippets
+        uses: gradle/gradle-build-action@v2
+        with:
+          arguments: check
+          build-root-directory: code_snippets/java

.gitignore

@@ -20,4 +20,12 @@ yarn-debug.log*
 yarn-error.log*
 
 .idea
-.yarn
+.yarn
+/code_snippets/ts/node_modules/
+/code_snippets/java/build/
+/code_snippets/java/.gradle/
+/code_snippets/ts/dist/
+/code_snippets/ts-grpc/src/generated/
+/code_snippets/ts-grpc/proto/buf.lock
+/code_snippets/ts-grpc/node_modules/
+/code_snippets/ts-grpc/dist/

README.md

@@ -32,12 +32,36 @@ This command generates static content into the `build` directory and can be serv
 
 The `main` branch of the documentation is continuously deployed at https://main.documentation-beg.pages.dev.
 
+## Adding code snippets
+If you want to add code snippets to the docs, they should be testable and compileable on PR merges and releases.
+Follow these steps:
+1. Add you code snippet in the folder [`code_snippets`](/code_snippets) in the subprojects for the respective language: [TypeScript](code_snippets/ts) or [Java](code_snippets/java). Keep the package structure identical to path of where the code snippet is referenced in the documentation.
+2. If you only want to use a section of the code snippet in the docs. Specify the start by specifying a comment `<start_here>` and the end by specifying a comment `<end_here>` inside the code snippet. For example:
+```
+greet: async (ctx: restate.Context, name: string) => {
+    // <start_here>
+    // option 1: use full API spec
+    ctx.send(myGreeterApi).greet("Pete");
+    // <end_here>
+},
+```
+You can also use custom tags. Please keep the tags a bit uniform and descriptive. For example, `// <start_custom_tag>` and `// <end_custom_tag>`. This way it's easy to discriminate tags from just comments.
+3. Refer to the code snippet from within the markdown documentation file as follows `CODE_LOAD::<path_to_snippet>`. If you use custom tags, specify them as  `CODE_LOAD::<path_to_snippet>#<start_custom_tag>-<end_custom_tag>`. You need to put this inside a code block with the language specified. The path is relative from **within** the code_snippets folder. For example, `CODE_LOAD::java/src/main/java/Greeter.java#<start_greet_function>-<end_greet_function`. 
+
+4. You can also use GitHub links for your code snippets. For example: 
+`CODE_LOAD::https://raw.githubusercontent.com/restatedev/examples/main/tutorials/tour-of-restate-typescript/src/part1/user_session.ts#<start_expire_ticket>-<end_expire_ticket>`
+
+
+Code snippets will be compiled and build on PRs and releases. 
+
+Details on how code snippets are parsed and inserted can be found in the [code-loader.js](src/plugins/code-loader.js) file.
+
 ## Releasing the documentation
 
 Before releasing the documentation, update schemas and version of Restate artifacts, either:
 
-* Automatically by executing the _Pre-release updates_ workflow.
-* Manually, as described [here](#manually-update-the-schemas).
+- Automatically by executing the _Pre-release updates_ workflow.
+- Manually, as described [here](#manually-update-the-schemas).
 
 Once the branch `main` is ready to be released, create and push the release tag:
 
@@ -63,7 +87,6 @@ $ ./tools/generate.sh <PATH to Restate repo clone>
 
 The config file `restate.config.json` contains versions of various Restate artifacts:
 
-* TypeScript SDK: `TYPESCRIPT_SDK_VERSION`
-* Java SDK: `JAVA_SDK_VERSION`
-* Runtime: `RESTATE_VERSION`
-* Tour: `TOUR_VERSION` (This counts for the TypeScript and Java Tour).
+- TypeScript SDK: `TYPESCRIPT_SDK_VERSION`
+- Java SDK: `JAVA_SDK_VERSION`
+- Runtime: `RESTATE_VERSION`

code_snippets/java/build.gradle.kts

@@ -0,0 +1,67 @@
+import com.google.protobuf.gradle.id
+
+plugins {
+  java
+  application
+  id("com.google.protobuf") version "0.9.1"
+}
+
+repositories {
+  mavenCentral()
+}
+
+val restateVersion = "0.8.0"
+
+dependencies {
+  // Restate SDK
+  implementation("dev.restate:sdk-api:$restateVersion")
+  implementation("dev.restate:sdk-http-vertx:$restateVersion")
+  implementation("dev.restate:sdk-lambda:$restateVersion")
+  // To use Jackson to read/write state entries (optional)
+  implementation("dev.restate:sdk-serde-jackson:$restateVersion")
+
+  // Protobuf and grpc dependencies
+  implementation("com.google.protobuf:protobuf-java:3.24.3")
+  implementation("io.grpc:grpc-stub:1.58.0")
+  implementation("io.grpc:grpc-protobuf:1.58.0")
+  // This is needed to compile the @Generated annotation forced by the grpc compiler
+  // See https://github.com/grpc/grpc-java/issues/9153
+  compileOnly("org.apache.tomcat:annotations-api:6.0.53")
+
+  // Logging (optional)
+  implementation("org.apache.logging.log4j:log4j-core:2.20.0")
+
+  // Testing (optional)
+  testImplementation("org.junit.jupiter:junit-jupiter:5.9.1")
+  testImplementation("dev.restate:sdk-testing:$restateVersion")
+}
+
+// Configure protoc plugin
+protobuf {
+  protoc { artifact = "com.google.protobuf:protoc:3.24.3" }
+
+  // We need both grpc and restate codegen(s) because the restate codegen depends on the grpc one
+  plugins {
+    id("grpc") { artifact = "io.grpc:protoc-gen-grpc-java:1.58.0" }
+    id("restate") { artifact = "dev.restate:protoc-gen-restate:$restateVersion:all@jar" }
+  }
+
+  generateProtoTasks {
+    all().forEach {
+      it.plugins {
+        id("grpc")
+        id("restate")
+      }
+    }
+  }
+}
+
+// Configure test platform
+tasks.withType<Test> {
+  useJUnitPlatform()
+}
+
+// Set main class
+application {
+  mainClass.set("develop.Greeter")
+}

code_snippets/java/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists