doc(examples): init

Author: nickkkccc

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

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

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/mkdocs.yml

@@ -41,10 +41,14 @@ plugins:
             Одиночный узел: Single Node
             Кластер TarantoolDB: TarantoolDB Cluster
             Кластер TQE: TQE Cluster
+            Примеры использования: Usage examples
+            Подключение к узлам: Connecting to nodes
   - drawio:
       darkmode: true
   - plantuml:
       puml_url: https://www.plantuml.com/plantuml/
+      # в секундах(in seconds)
+      request_timeout: 300
 
 theme:
   features:
@@ -118,6 +122,8 @@ 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
       - Tarantool Testcontainers:
           - documentation/testcontainers/index.md
           - Одиночный узел:
@@ -139,7 +145,6 @@ markdown_extensions:
   - tables
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
   - footnotes
@@ -154,10 +159,17 @@ 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
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
 
 exclude_docs: |
   venv