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

@@ -1,33 +1,99 @@
-## Documentation
+## Документация
 
-### Local Build
+### Локальная сборка документации
 
-To deploy the site locally on the current branch/tag:
+Чтобы собрать документацию локально на текущей ветке/теге:
 
-1.  ```bash
+1. Перейдите на ветку/тег и инициализируйте python-окружение:
+
+    ```shell
     git checkout <branch/tag>
-    ```
-2. ```bash
     cd documentation
-    ```
-3. ```bash
     python3 -m venv venv
-    ```
-4. ```bash
     source venv/bin/activate
-    ```
-5. ```bash
     pip install -r requirements.txt
     ```
-6. ```bash
-    mkdocs serve 
+
+2. Соберите или запустите сайт:
+
+   ```shell
+   mkdocs build
+   ```
+
+   ```shell
+   mkdocs serve
     ```
 
-### Schemas
+### Интернационализация
+
+На данный момент документация поддерживает два языка:
+
+- Русский 🇷🇺 - по умолчанию
+- Английский 🇺🇸
+
+### Правила написания новых страниц и разделов
+
+#### Раздел
+
+`Раздел` - группа страниц, описывающая одну конкретную тему. Раздел может включать подразделы.
+Раздел оформаляется в отдельной директории. Каждый раздел обязан иметь страницу с именем `index.md`,
+в которой описывается тематика раздела.
+
+`Страница` - страница с произвольным именем и расширением `.md`, написанная на `markdown`.
+
+При добавлении страницы и раздела, добавьте их в секцию `nav` в файле `mkdocs.yml`:
 
-Documentation supports `.drawio` format schemas. Place your schema in the `assets` directory. In the markdown text,
-refer to the schema as a regular markdown image. The path to the image must be relative:
+Пример раздела:
+
+> ![alt](readme-images/sections.png)
+
+Пример оформленной навигации для этого раздела:
+
+> ![alt](readme-images/navigation.png)
+
+### Схемы
+
+#### Plantuml
+
+Документация поддерживает рендеринг `plantuml-диаграмм`. Для того чтобы добавить схему plantuml в
+текст страницы `markdown` используйте блок кода с расширением `puml`:
+
+> \`\`\`puml
+>
+> @startuml
+>
+> Alice -> Bob: test
+>
+> @enduml
+>
+> \`\`\`
+
+#### Drawio
+
+Документация поддерживает отображение схем, написанных в `drawio` (файлы с расширением `.drawio`).
+Необходимо добавить схему в директорию `assets`. В тексте markdown добавьте схему также как
+добавляете обыное изображение, используя относительный путь:
 
 ```markdown
 ![](../../../../assets/<some-paths>/schema.drawio)
 ```
+
+### Code Snippets
+
+Документация поддерживает добавление в текст markdown включение текста из других файлов (snippets).
+Для того, чтобы добавить snippet в текст markdown изучите
+документацию [расширения](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/).
+Путь к файлам, которые будут включены вычисляется относительно директории
+`docs/documentation/examples`.
+
+#### Дополнительные возможности
+
+Также поддерживаются следующие дополнения:
+
+- Использование [emoji](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) в
+  тексте страниц.
+- [Табы](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/)
+- [Сноски](https://squidfunk.github.io/mkdocs-material/reference/footnotes/)
+- [Диаграммы mermaid](https://squidfunk.github.io/mkdocs-material/reference/diagrams/)
+- [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
+- [Аннотации](https://squidfunk.github.io/mkdocs-material/reference/annotations/)

documentation/README_EN.md

@@ -0,0 +1,98 @@
+## Documentation
+
+### Local documentation deploy
+
+To deploy documentation locally on current branch/tag:
+
+1. Checkout branch/tag and initialize python-environment:
+
+    ```shell
+    git checkout <branch/tag>
+    cd documentation
+    python3 -m venv venv
+    source venv/bin/activate
+    pip install -r requirements.txt
+    ```
+
+2. Build or serve site:
+
+   ```shell
+   mkdocs build
+   ```
+
+   ```shell
+   mkdocs serve
+    ```
+
+### Internationalization
+
+Documentation supports two languages:
+
+- Russian 🇷🇺 - by default
+- English 🇺🇸
+
+### New pages writing rules
+
+#### Section
+
+`Section` is group of pages, describing one certain topic. Section can include subsections. Write
+section on separate directory. Each section must have page with `index.md` name that describe topic
+area.
+
+`Page` is page with any name and `.md` extension.
+
+When a new section and page are being written, they should be added to the `nav` section in the
+`mkdocs.yml` file.
+
+Section example:
+
+> ![alt](readme-images/sections.png)
+
+Example of a decorated navigation for this section:
+
+> ![alt](readme-images/navigation.png)
+
+### Схемы
+
+#### Plantuml
+
+The documentation supports the rendering of `plantuml diagrams`. To add the plantuml schema to the
+text of the `markdown` page, use a block of code with the `puml` extension.:
+
+> \`\`\`puml
+>
+> @startuml
+>
+> Alice -> Bob: test
+>
+> @enduml
+>
+> \`\`\`
+
+#### Drawio
+
+The documentation supports the display of diagrams written in `drawio` (files with the `.drawio`
+extension). It is necessary to add the schema to the `assets` directory. In the Markdown text, add a
+diagram in the same way as you add an image using a relative path:
+
+```markdown
+![](../../../../assets/<some-paths>/schema.drawio)
+```
+
+### Code Snippets
+
+The documentation supports adding text inclusions from other files (snippets) to the Markdown text.
+To add snippet to the Markdown text, read the
+extension's [documentation](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/).
+The path to the files to be included is calculated relative to the `docs/documentation/examples`
+directory.
+
+#### Additional extensions
+
+- Usage of [emoji](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/) in Markdown
+  pages
+- [Tabs of content](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/)
+- [Footnotes](https://squidfunk.github.io/mkdocs-material/reference/footnotes/)
+- [Mermaid diagrams](https://squidfunk.github.io/mkdocs-material/reference/diagrams/)
+- [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
+- [Annotations](https://squidfunk.github.io/mkdocs-material/reference/annotations/)

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

@@ -0,0 +1,7 @@
+---
+title: Connection to nodes
+hide:
+  - toc
+---
+
+This section provides examples of connecting to Tarantool using the `tarantool-java-sdk`.

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.en.md

@@ -0,0 +1,34 @@
+---
+title: Connection to single node Tarantool
+---
+
+To connect to a single node, run the following code:
+
+=== "tarantool-java-sdk"
+
+    ```java title="Connection to single node Tarantool"
+    --8<-- "src/client/examples/connection/single/SingleNodeConnectionNewConnectorExample.java:new-simple-connection"
+    ```
+
+    ```java title="Parent abstract class to create docker container"
+    --8<-- "src/client/examples/connection/single/SingleNodeConnectionAbstractExample.java:single-node-connection"
+    ```    
+
+    ```java title="Class to create container"
+    --8<-- "src/testcontainers/utils/SingleNodeConfigUtils.java:create-single-node"
+    ```
+
+=== "cartridge-java"
+
+    ```java title="Connection to single node Tarantool"
+    --8<-- "src/client/examples/connection/single/SingleNodeConnectionCartridgeJavaExample.java:old-simple-connection"
+    ```
+
+    ```java title="Parent abstract class to create docker container"
+    --8<-- "src/client/examples/connection/single/SingleNodeConnectionAbstractExample.java:single-node-connection"
+    ```    
+
+    ```java title="Class to create container"
+    --8<-- "src/testcontainers/utils/SingleNodeConfigUtils.java:create-single-node"
+    ```
+

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

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

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

@@ -0,0 +1,12 @@
+---
+title: Usage examples
+hide:
+  - toc
+---
+
+This section provides examples of using the `tarantool-java-sdk`.
+
+???+ note
+
+    Where possible, the code is compared with 
+    [cartridge-java](https://github.com/tarantool/cartridge-java)

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)