Documentation hosting on Github Pages

.github/workflows/ci.yml

@@ -12,6 +12,10 @@ on:
   push:
     branches: ["master"]
 
+concurrency:
+  group: "${{ github.workflow }}-${{ github.ref_name }}"
+  cancel-in-progress: "${{ github.ref_name != github.event.repository.default_branch }}"
+
 jobs:
   create-semantic-tag:
     runs-on: "ubuntu-latest"
@@ -62,3 +66,7 @@ jobs:
     uses: "./.github/workflows/release.yml"
     with:
       release_name: "${{ needs.create-semantic-tag.outputs.RELEASE_VERSION }}"
+
+  deploy-docs:
+    needs: ["release-latest"]
+    uses: "./.github/workflows/deploy-docs.yml"

.github/workflows/deploy-docs.yml

@@ -0,0 +1,38 @@
+name: "Deploy docs"
+
+on:
+  workflow_call:
+
+jobs:
+  deploy:
+    permissions:
+      pages: "write"
+      id-token: "write"
+
+    environment:
+      name: "github-pages"
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: "actions/checkout@v4"
+
+      - name: "Set up Python"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: '3.x'
+
+      - name: "Install requirements"
+        run: "pip install -r doc/common/requirements.txt"
+
+      - name: "Build site"
+        run: "mkdocs build --strict --site-dir ./site"
+
+      - name: "Upload artifact"
+        uses: "actions/upload-pages-artifact@v3"
+        with:
+          path: "./site"
+
+      - name: "Deploy to GitHub Page"
+        id: "deployment"
+        uses: "actions/deploy-pages@v4"

.gitignore

@@ -16,7 +16,7 @@ config/*
 !config/config.yml
 !config/models.yml
 
-### Go template
+### Go
 
 # Binaries for programs and plugins
 *.exe
@@ -37,6 +37,117 @@ vendor/
 # Go workspace file
 go.work
 
+### Python
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Translations
+*.mo
+*.pot
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
 ### VSCode
 
 .vscode

Makefile

@@ -24,3 +24,4 @@ test/performance:
 
 include ./build/package/Makefile
 include ./build/ci/Makefile
+include ./doc/common/Makefile

README.md

@@ -1,5 +1,9 @@
+<div class="hide-in-mkdocs">
+
 # Synthetic Data Values Generator (SDVG)
 
+</div>
+
 [![Release][release-badge]][release-url]
 [![Pre-release][pre-release-badge]][pre-release-url]
 [![CI][actions-badge]][actions-url]
@@ -20,18 +24,22 @@
 [license-badge]: https://img.shields.io/github/license/tarantool/sdvg
 [license-url]: ./LICENSE
 
-![scheme.png](asset/scheme.png)
-
-## Language
+<div class="hide-in-mkdocs">
 
+## Documentation version
+- [Multilingual web version](https://tarantool.github.io/sdvg/) (recommended)
 - **English**
 - [Русский](README.ru.md)
 
+</div>
+
 ## Description
 
 SDVG (Synthetic Data Values Generator) is a tool for generating synthetic data.
 It supports various run modes, data types for generation, and output formats.
 
+![scheme.png](./asset/scheme.png)
+
 Run modes:
 
 - CLI - generate data, create configs, and validate them via the console;

README.ru.md

@@ -1,5 +1,10 @@
+<div class="hide-in-mkdocs">
+
 # Synthetic Data Values Generator (SDVG)
 
+
+</div>
+
 [![Release][release-badge]][release-url]
 [![Pre-release][pre-release-badge]][pre-release-url]
 [![CI][actions-badge]][actions-url]
@@ -20,18 +25,22 @@
 [license-badge]: https://img.shields.io/github/license/tarantool/sdvg
 [license-url]: ./LICENSE
 
-![scheme.png](asset/scheme.png)
-
-## Язык
+<div class="hide-in-mkdocs">
 
+## Версия документации
+- [Многоязычная веб-версия](https://tarantool.github.io/sdvg/ru/) (рекомендуется)
 - [English](README.md)
 - **Русский**
 
+</div>
+
 ## Описание продукта
 
 SDVG (Synthetic Data Values Generator) — это инструмент для генерации синтетических данных.
 Он поддерживает различные форматы запуска, типы данных для генерации и форматы вывода.
 
+![scheme.png](./asset/scheme.png)
+
 Форматы запуска:
 
 - CLI - генерация данных, создание конфигураций и их валидация через консоль;

doc/common/Makefile

@@ -0,0 +1,15 @@
+default: docs
+all: default
+
+docs: docs/prepare docs/serve
+
+docs/prepare:
+	pip install -r ./doc/common/requirements.txt
+
+docs/serve:
+	mkdocs serve \
+      --dev-addr "127.0.0.1:8000" \
+      --open \
+      --strict \
+      --clean \
+      -f ./mkdocs.yml

doc/common/extra.css

@@ -0,0 +1,7 @@
+.hide-in-mkdocs {
+    display: none;
+}
+
+.md-header__title {
+    margin-left: 0 !important;
+}

doc/common/hooks.py

@@ -0,0 +1,32 @@
+import re
+
+def replace_specific_links(markdown, *, page, config, files, **kwargs):
+    # Replace link from /CHANGELOG.md to page with changelog
+    markdown = re.sub(
+        r'\[([^]]+)](\(|:\s*).*CHANGELOG.md(\)|\s*)',
+        r'[\1]\2changelog.md\3',
+        markdown
+    )
+
+    # Replace link from /LICENSE to page with license
+    markdown = re.sub(
+        r'\[([^]]+)](\(|:\s*).*LICENSE(\)|\s*)',
+        r'[\1]\2license.md\3',
+        markdown
+    )
+
+    # Replace links for assets
+    markdown = re.sub(
+        r'\[([^]]+)](\(|:\s*)(\.\./){2}(asset/.+)(\)|\s*)',
+        rf'[\1]\2https://raw.githubusercontent.com/{config.repo_name}/refs/heads/master/\4\5',
+        markdown
+    )
+
+    # Replace links for code
+    markdown = re.sub(
+        r'\[([^]]+)](\(|:\s*)(\.\./){2}(.+)(\)|\s*)',
+        rf'[\1]\2{config.repo_url}/tree/master/\4\5',
+        markdown
+    )
+
+    return markdown

doc/common/requirements.txt

@@ -0,0 +1,6 @@
+mkdocs==1.6.1
+mkdocs-static-i18n==1.3.0
+mkdocs-material==9.6.15
+mkdocs-include-markdown-plugin==7.1.6
+mkdocs-simple-hooks==0.1.5
+pymdown-extensions==10.16

doc/en/changelog.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

doc/en/contributing.md

@@ -32,3 +32,23 @@ To release a new version:
 2. Add a new header for the release version with a link to the git diff in [CHANGELOG.md](../../CHANGELOG.md).
    Use the format: `## [0.0.0](https://.../compare/prev...current) - 2000-12-31`.
 3. Commit to the main branch (via MR) with a commit message containing `release 0.0.0`.
+
+## Documentation
+
+To edit the documentation, you need to make changes for each supported language
+within its corresponding directory in the [./doc](../../doc) directory.
+
+To add a new section to the documentation, you must:
+
+1. Create a new `.md` file in the root of the [doc/en](../../doc/en) directory.
+2. Add the file name to the `nav` section in the [mkdocs.yml](../../mkdocs.yml) configuration file.
+3. Perform the same steps for other languages if they need to be supported.
+   Otherwise, the English version of the section will be displayed.
+4. Translate the section titles for other languages in the `plugins.i18n.languages.<language_code>.nav_translations`
+section of [mkdocs.yml](../../mkdocs.yml).
+
+To locally check the documentation site's layout, you need to:
+
+1. Install the Python dependencies: `make docs/prepare`.
+2. Run the local site hosting with the command `make docs/serve`.
+   The site will be available at [127.0.0.1:8000](http://127.0.0.1:8000).

doc/en/index.md

@@ -0,0 +1,3 @@
+# Home
+
+{% include-markdown "../../README.md" rewrite-relative-urls=true %}

doc/en/license.md

@@ -0,0 +1 @@
+../../LICENSE

doc/en/overview.md

@@ -1,12 +1,16 @@
 # Goals and Standards Compliance
 
+<div class="hide-in-mkdocs">
+
 ## Table of Contents
 
 - [Tool Benefits](#tool-benefits)
 - [User Stories](#user-stories)
 - [VK Tech Values](#vk-tech-values)
 - [CNCF Standards Compliance](#cncf-standards-compliance)
 
+</div>
+
 ## Tool Benefits
 
 With the rise of tools for working with large datasets (millions of rows) and large language models (LLMs),

doc/en/usage.md

@@ -1,5 +1,7 @@
 # User Guide
 
+<div class="hide-in-mkdocs">
+
 ## Table of Contents
 
 - [Configuration](#configuration)
@@ -14,6 +16,8 @@
   - [Ignoring conflicts](#ignoring-conflicts)
   - [Continuing generation](#continuing-generation)
 
+</div>
+
 ## Configuration
 
 SDVG uses two configuration files: the SDVG instance configuration file and the data generation configuration file.