feat(documentation): add maven project with documentation

.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
 
       - name: Publish to Maven Central
         run: |
-          ./mvnw -B clean deploy -PsonatypeRelease -DskipTests -pl '!jacoco-coverage-aggregate-report'
+          ./mvnw -B clean deploy -PsonatypeRelease -DskipTests -pl '!jacoco-coverage-aggregate-report,!documentation'
         env:
           MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USER }}
           MAVEN_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }}

.github/workflows/snapshot.yml

@@ -27,7 +27,7 @@ jobs:
 
       - name: Publish Snapshot to Maven Central
         run: |
-          ./mvnw -B clean deploy -PsonatypeSnapshot -DskipTests -pl '!jacoco-coverage-aggregate-report'
+          ./mvnw -B clean deploy -PsonatypeSnapshot -DskipTests -pl '!jacoco-coverage-aggregate-report,!documentation'
         env:
           MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USER }}
           MAVEN_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }}

.gitignore

@@ -23,3 +23,4 @@ workbench.xmi
 .factorypath
 documentation/venv
 documentation/site
+documentation/target

documentation/README.md

@@ -32,3 +32,8 @@ markdown сошлитесь на схему как на обычную markdown-
 ```markdown
 ![](../../../../assets/<some-paths>/schema.drawio)
 ```
+
+### Code Snippets
+
+Сейчас документация настроена на то, что пути snippet файлов обрабатываются относительно директории
+`docs/documentation/examples`

documentation/docs/documentation/client/examples/connection/index.md

@@ -0,0 +1,7 @@
+---
+title: Подключение к узлам
+hide:
+  - toc
+---
+
+В данном разделе приводятся примеры подключения к Tarantool с помощью `tarantool-java-sdk`.

documentation/docs/documentation/client/examples/connection/single-node.md

@@ -0,0 +1,34 @@
+---
+title: Подключение к одиночному узлу
+---
+
+Для того чтобы подключиться к одиночному узлу необходимо выполнить следующий код:
+
+=== "tarantool-java-sdk"
+
+    ```java title="Подключение к одному узлу Tarantool"
+    --8<-- "src/client/simple/connection/SingleNodeConnectionNewConnector.java:new-simple-connection"
+    ```
+
+    ```java title="Родительский класс с созданием контейнера"
+    --8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection"
+    ```    
+
+    ```java title="Класс, который создает контейнер"
+    --8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node"
+    ```
+
+=== "cartridge-java"
+
+    ```java title="Подключение к одному узлу Tarantool"
+    --8<-- "src/client/simple/connection/SingleNodeConnectionCartridgeJava.java:old-simple-connection"
+    ```
+
+    ```java title="Родительский класс с созданием контейнера"
+    --8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection"
+    ```    
+
+    ```java title="Класс, который создает контейнер"
+    --8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node"
+    ```
+

documentation/docs/documentation/client/examples/index.md

@@ -0,0 +1,12 @@
+---
+title: Примеры использования
+hide:
+  - toc
+---
+
+В разделе приводятся примеры использования `tarantool-java-sdk`.
+
+???+ note "Заметка"
+
+    Где это возможно, производится сравнение кода с 
+    [cartridge-java](https://github.com/tarantool/cartridge-java)

documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnection.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client.simple.connection;
+
+// --8<-- [start:single-node-connection]
+
+import java.io.IOException;
+import java.nio.file.Path;
+
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.io.TempDir;
+import org.testcontainers.containers.tarantool.Tarantool3Container;
+import org.testcontainers.containers.tarantool.TarantoolContainer;
+import org.testcontainers.utility.DockerImageName;
+import testcontainers.single.CreateSingleNode;
+
+public abstract class SingleNodeConnection {
+
+  @TempDir protected static Path TEMP_DIR;
+
+  private static final DockerImageName image = DockerImageName.parse("tarantool/tarantool:3.4.1");
+
+  protected static TarantoolContainer<Tarantool3Container> CONTAINER;
+
+  @BeforeAll
+  static void beforeAll() throws IOException {
+    CONTAINER = createSingleNodeContainer(TEMP_DIR);
+    CONTAINER.start();
+  }
+
+  protected abstract void simpleConnection();
+
+  protected static TarantoolContainer<Tarantool3Container> createSingleNodeContainer(Path tempPath)
+      throws IOException {
+    final Path pathToConfig = CreateSingleNode.createSingleNodeConfig(tempPath);
+    return new Tarantool3Container(image, "test-node").withConfigPath(pathToConfig);
+  }
+}
+// --8<-- [end:single-node-connection]

documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionCartridgeJava.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client.simple.connection;
+
+// --8<-- [start:old-simple-connection]
+
+import java.net.InetSocketAddress;
+import java.util.List;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import testcontainers.single.CreateSingleNode;
+
+import io.tarantool.driver.api.TarantoolClient;
+import io.tarantool.driver.api.TarantoolClientFactory;
+import io.tarantool.driver.api.TarantoolResult;
+import io.tarantool.driver.api.tuple.TarantoolTuple;
+
+public class SingleNodeConnectionCartridgeJava extends SingleNodeConnection {
+
+  @Test
+  @Override
+  protected void simpleConnection() {
+    try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
+      final List<?> result = client.eval("return _TARANTOOL").join();
+
+      Assertions.assertEquals(1, result.size());
+
+      final Object object = result.get(0);
+
+      Assertions.assertInstanceOf(String.class, object);
+      Assertions.assertTrue(((String) object).contains("3.4.1"));
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
+
+  private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
+    // Получаем адрес и порт из докера
+    final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
+
+    return TarantoolClientFactory.createClient()
+        .withAddress(nodeAddress.getHostName(), nodeAddress.getPort())
+        .withCredentials(CreateSingleNode.LOGIN, CreateSingleNode.PWD.toString())
+        .build();
+  }
+}
+// --8<-- [end:old-simple-connection]

documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionNewConnector.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client.simple.connection;
+
+// --8<-- [start:new-simple-connection]
+
+import java.net.InetSocketAddress;
+import java.util.Collections;
+import java.util.List;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import testcontainers.single.CreateSingleNode;
+
+import io.tarantool.client.box.TarantoolBoxClient;
+import io.tarantool.client.factory.TarantoolBoxClientBuilder;
+import io.tarantool.client.factory.TarantoolFactory;
+import io.tarantool.mapping.TarantoolResponse;
+import io.tarantool.pool.InstanceConnectionGroup;
+
+public class SingleNodeConnectionNewConnector extends SingleNodeConnection {
+
+  @Test
+  @Override
+  protected void simpleConnection() {
+    // Получаем адрес и порт из докера
+    final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
+
+    // Настраиваем группу подключения
+    final InstanceConnectionGroup connectionGroup =
+        InstanceConnectionGroup.builder()
+            .withHost(nodeAddress.getHostName())
+            .withPort(nodeAddress.getPort())
+            .withUser(CreateSingleNode.LOGIN)
+            .withPassword(CreateSingleNode.PWD.toString())
+            .build();
+
+    final TarantoolBoxClientBuilder clientBuilder =
+        TarantoolFactory.box().withGroups(Collections.singletonList(connectionGroup));
+
+    try (final TarantoolBoxClient singleNodeClient = clientBuilder.build()) {
+
+      final TarantoolResponse<List<String>> response =
+          singleNodeClient.eval("return _TARANTOOL", String.class).join();
+      final List<String> results = response.get();
+
+      Assertions.assertEquals(1, results.size());
+      Assertions.assertTrue(results.get(0).contains("3.4.1"));
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
+}
+// --8<-- [end:new-simple-connection]

documentation/docs/documentation/examples/src/testcontainers/single/CreateSingleNode.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package testcontainers.single;
+
+// --8<-- [start:create-single-node]
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Collections;
+
+import org.testcontainers.containers.tarantool.config.ConfigurationUtils;
+
+import io.tarantool.autogen.Tarantool3Configuration;
+import io.tarantool.autogen.credentials.Credentials;
+import io.tarantool.autogen.credentials.users.Users;
+import io.tarantool.autogen.credentials.users.usersProperty.UsersProperty;
+import io.tarantool.autogen.groups.Groups;
+import io.tarantool.autogen.groups.groupsProperty.GroupsProperty;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.Replicasets;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.ReplicasetsProperty;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.Instances;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.InstancesProperty;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.Iproto;
+import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.listen.Listen;
+
+public class CreateSingleNode {
+
+  public static final String NODE = "test-node";
+
+  public static final CharSequence PWD = "secret";
+
+  public static final String LOGIN = "test-user";
+
+  /*
+  Создает конфигурацию вида:
+    ---
+    credentials:
+      users:
+        test-user:
+          password: "secret"
+          roles:
+          - "super"
+    groups:
+      test-group:
+        replicasets:
+          test-rs:
+            instances:
+              test-node:
+                iproto:
+                  listen:
+                  - uri: "0.0.0.0:3301"
+   */
+  public static Path createSingleNodeConfig(Path tempDir) throws IOException {
+    final Path pathToConfigFile = Files.createFile(tempDir.resolve("config.yaml"));
+
+    final Credentials credentials =
+        Credentials.builder()
+            .withUsers(
+                Users.builder()
+                    .withAdditionalProperty(
+                        LOGIN,
+                        UsersProperty.builder()
+                            .withRoles(Collections.singletonList("super"))
+                            .withPassword(PWD.toString())
+                            .build())
+                    .build())
+            .build();
+
+    final Iproto iproto =
+        Iproto.builder()
+            .withListen(Collections.singletonList(Listen.builder().withUri("0.0.0.0:3301").build()))
+            .build();
+
+    final InstancesProperty instance = InstancesProperty.builder().withIproto(iproto).build();
+
+    final ReplicasetsProperty replicaset =
+        ReplicasetsProperty.builder()
+            .withInstances(Instances.builder().withAdditionalProperty(NODE, instance).build())
+            .build();
+
+    final GroupsProperty group =
+        GroupsProperty.builder()
+            .withReplicasets(
+                Replicasets.builder().withAdditionalProperty("test-rs", replicaset).build())
+            .build();
+
+    final Tarantool3Configuration configuration =
+        Tarantool3Configuration.builder()
+            .withGroups(Groups.builder().withAdditionalProperty("test-group", group).build())
+            .withCredentials(credentials)
+            .build();
+
+    ConfigurationUtils.writeToFile(configuration, pathToConfigFile);
+    return pathToConfigFile;
+  }
+}
+
+// --8<-- [end:create-single-node]

documentation/mkdocs.yml

@@ -94,6 +94,11 @@ nav:
               - documentation/client/arch/connection-to-multiple-nodes.md
               - documentation/client/arch/call.md
               - documentation/client/arch/tuple_pojo_mapping.md
+          - Примеры использования:
+              - documentation/client/examples/index.md
+              - Подключение к узлам:
+                  - documentation/client/examples/connection/index.md
+                  - documentation/client/examples/connection/single-node.md
       - Tarantool Testcontainers:
           - documentation/testcontainers/index.md
           - Одиночный узел:
@@ -130,7 +135,9 @@ markdown_extensions:
       line_spans: __spanz
       pygments_lang_class: true
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      check_paths: true
+      base_path: docs/documentation/examples
   - def_list
   - pymdownx.tasklist:
       custom_checkbox: true