Add executable documentation examples and dedicated CI

.github/workflows/ydb-tech.yml

@@ -0,0 +1,34 @@
+name: ydb.tech examples
+
+on:
+  pull_request:
+  push:
+    branches: [master, docs/topic-snippets]
+
+concurrency:
+  group: ydb-tech-examples-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  examples:
+    name: Examples (ydb_tech)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    services:
+      ydb:
+        image: ydbplatform/local-ydb:trunk
+        ports: ["2136:2136", "8765:8765"]
+        env:
+          YDB_USE_IN_MEMORY_PDISKS: true
+        options: '-h localhost'
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-java@v5
+        with:
+          java-version: '17'
+          distribution: temurin
+          cache: maven
+      - run: bash ydb_tech/run.sh

ydb_tech/README.md

@@ -0,0 +1,26 @@
+# Executable documentation examples
+
+`ydb_tech` contains the executable sources used by ydb.tech documentation.
+The `Examples (ydb_tech)` CI job builds and runs every registered example against
+this checkout and a local YDB instance.
+
+Run all examples from the repository root:
+
+```sh
+bash ydb_tech/run.sh
+```
+
+Each example has its own directory and a `run.sh` entry point. The common runner
+finds these entry points automatically and fails if any example fails or times out.
+It requires Python 3 for portable process timeouts. Set `YDB_TECH_TIMEOUT_SECONDS`
+to change the default 180-second limit per example.
+
+To add an example:
+
+1. Add a directory with executable source and a `run.sh` entry point.
+2. Register its project in the SDK build if the language requires it.
+3. Mark documentation regions with `[BEGIN name]` and `[END name]` comments.
+4. Keep each region nonempty, unique within its file, and free of nested regions.
+
+No workflow changes are needed for a new example. The topic example is the first
+scenario; its README describes SDK-specific build and connection settings.

ydb_tech/run.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+examples_root="$(cd "$(dirname "$0")" && pwd)"
+repo_root="$(dirname "$examples_root")"
+cd "$repo_root"
+example_count=0
+for entry in "$examples_root"/*/run.sh; do
+    [[ -f "$entry" ]] || continue
+    example_count=$((example_count + 1))
+    printf 'Running %s\n' "${entry%/run.sh}"
+    python3 - "$entry" "${YDB_TECH_TIMEOUT_SECONDS:-180}" <<'PYTHON'
+import subprocess
+import sys
+
+try:
+    result = subprocess.run(["bash", sys.argv[1]], timeout=int(sys.argv[2]), check=False)
+except subprocess.TimeoutExpired:
+    print("Example exceeded its time limit: " + sys.argv[1], file=sys.stderr)
+    raise SystemExit(124)
+raise SystemExit(result.returncode)
+PYTHON
+done
+if [[ "$example_count" == 0 ]]; then
+    printf 'No executable examples found in %s\n' "$examples_root" >&2
+    exit 1
+fi

ydb_tech/topic/README.md

@@ -0,0 +1,16 @@
+# Topic examples for ydb.tech
+
+This application supplies the Java snippets in the topic reference on ydb.tech.
+The runner builds and installs this checkout, reads its SDK version and passes that
+version to the example. No SDK version is hardcoded in the example POM.
+
+With JDK 8 or newer, Maven and a local YDB instance, run from the repository root:
+
+```sh
+bash ydb_tech/topic/run.sh
+```
+
+`YDB_CONNECTION_STRING` defaults to `grpc://localhost:2136/local`.
+The application checks management, sync and async writers/readers, acknowledgments,
+metadata, compression, selectors, external commits and transactions. Topics have unique names.
+The offset callback uses an in-memory store; use persistent storage for production recovery.

ydb_tech/topic/pom.xml

@@ -0,0 +1,41 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <groupId>tech.ydb.examples</groupId>
+    <artifactId>ydb-tech-topic</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <properties>
+        <maven.compiler.release>8</maven.compiler.release>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+    <dependencies>
+        <dependency>
+            <groupId>tech.ydb</groupId>
+            <artifactId>ydb-sdk-topic</artifactId>
+            <version>${ydb.sdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>tech.ydb</groupId>
+            <artifactId>ydb-sdk-table</artifactId>
+            <version>${ydb.sdk.version}</version>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.14.1</version>
+            </plugin>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <version>3.5.0</version>
+                <configuration>
+                    <mainClass>tech.ydb.examples.topic.TopicExample</mainClass>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

ydb_tech/topic/run.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+topic_sdk_version=$(mvn -q -Dstyle.color=never help:evaluate -Dexpression=project.version -DforceStdout)
+mvn -B -DskipTests install
+mvn -B -f ydb_tech/topic/pom.xml -Dydb.sdk.version="$topic_sdk_version" compile exec:java