Documentation hosting on Github Pages (#11)

Before this PR, the only way to access the documentation was by browsing through the repository's markdown files.
Using the mkdocs framework, an alternative way was created to view documentation as a website.

This patch contains:
- Mkdocs config file `mkdocs.yml`.
- Small corrections in .md files for more correct rendering on the website.
- Custom hooks before site build to ensure .md file links remain
  accurate in both the website and repository versions of the docs.
- CI workflow to deploy the documentation site to GitHub Pages.

To check how the site looks locally, you need to:

```
make doc
```

Open documentation on http://localhost:8000/

Important:
- In the repository settings, set the Github Actions source for Github Pages.
  Settings -> Pages -> Build and deployment: "GitHub Actions"
- The documentation is deployed in the `github-pages` environment.
  You can set up rules for each environment (for example, a timer for deferred deployment)
  Settings -> Environment -> [env-name]

Co-authored-by: Vladimir Severov <[email protected]>

Author: Hoodie-Huuuuu

.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/doc.yml"

.github/workflows/doc.yml

@@ -0,0 +1,36 @@
+name: "Documentation"
+
+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: "make doc/prepare"
+
+      - name: "Build site"
+        run: "make doc/build"
+
+      - 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,116 @@ vendor/
 # Go workspace file
 go.work
 
+### Python
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+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/build/Makefile

README.md

@@ -1,37 +1,46 @@
+<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]
 [![Coverage Status][test-coverage-badge]][test-coverage-url]
 [![Language][language-badge]][language-url]
 [![License][license-badge]][license-url]
 
-[release-badge]: https://img.shields.io/github/v/release/tarantool/sdvg
+[release-badge]: https://badgen.net/github/release/tarantool/sdvg/stable?color=pink
 [release-url]: https://github.com/tarantool/sdvg/releases/latest/
-[pre-release-badge]: https://img.shields.io/badge/pre--release-latest-orange
+[pre-release-badge]: https://badgen.net/static/pre-release/latest/orange?color=purple
 [pre-release-url]: https://github.com/tarantool/sdvg/releases/tag/latest/
-[actions-badge]: https://img.shields.io/github/check-runs/tarantool/sdvg/master
+[actions-badge]: https://badgen.net/github/checks/tarantool/sdvg
 [actions-url]: https://github.com/tarantool/sdvg/actions
-[test-coverage-badge]: https://img.shields.io/coverallsCoverage/github/tarantool/sdvg?branch=master
+[test-coverage-badge]: https://badgen.net/coveralls/c/github/tarantool/sdvg
 [test-coverage-url]: https://coveralls.io/github/tarantool/sdvg?branch=master
-[language-badge]: https://img.shields.io/github/languages/top/tarantool/sdvg
+[language-badge]: https://badgen.net/static/language/go/blue
 [language-url]: https://github.com/tarantool/sdvg/search?l=go
-[license-badge]: https://img.shields.io/github/license/tarantool/sdvg
+[license-badge]: https://badgen.net/github/license/tarantool/sdvg?color=cyan
 [license-url]: ./LICENSE
 
-![scheme.png](asset/scheme.png)
+<div class="hide-in-mkdocs">
 
-## Language
+## 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;
@@ -180,7 +189,7 @@ sdvg generate -h
 
 More information can be found in the [user guide](./doc/en/usage.md).
 
-## Documentation
+## Next Steps
 
 - [User Guide](./doc/en/usage.md)
 - [Developer Guide](./doc/en/contributing.md)

README.ru.md

@@ -1,37 +1,46 @@
+<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]
 [![Coverage Status][test-coverage-badge]][test-coverage-url]
 [![Language][language-badge]][language-url]
 [![License][license-badge]][license-url]
 
-[release-badge]: https://img.shields.io/github/v/release/tarantool/sdvg
+[release-badge]: https://badgen.net/github/release/tarantool/sdvg/stable?color=pink
 [release-url]: https://github.com/tarantool/sdvg/releases/latest/
-[pre-release-badge]: https://img.shields.io/badge/pre--release-latest-orange
+[pre-release-badge]: https://badgen.net/static/pre-release/latest/orange?color=purple
 [pre-release-url]: https://github.com/tarantool/sdvg/releases/tag/latest/
-[actions-badge]: https://img.shields.io/github/check-runs/tarantool/sdvg/master
+[actions-badge]: https://badgen.net/github/checks/tarantool/sdvg
 [actions-url]: https://github.com/tarantool/sdvg/actions
-[test-coverage-badge]: https://img.shields.io/coverallsCoverage/github/tarantool/sdvg?branch=master
+[test-coverage-badge]: https://badgen.net/coveralls/c/github/tarantool/sdvg
 [test-coverage-url]: https://coveralls.io/github/tarantool/sdvg?branch=master
-[language-badge]: https://img.shields.io/github/languages/top/tarantool/sdvg
+[language-badge]: https://badgen.net/static/language/go/blue
 [language-url]: https://github.com/tarantool/sdvg/search?l=go
-[license-badge]: https://img.shields.io/github/license/tarantool/sdvg
+[license-badge]: https://badgen.net/github/license/tarantool/sdvg?color=cyan
 [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 - генерация данных, создание конфигураций и их валидация через консоль;
@@ -180,7 +189,7 @@ sdvg generate -h
 
 Больше информации можно найти в [руководстве по эксплуатации](./doc/ru/usage.md).
 
-## Документация
+## Следующие шаги
 
 - [Руководство по эксплуатации](./doc/ru/usage.md)
 - [Руководство для разработчиков](./doc/ru/contributing.md)

asset/favicon.png

@@ -0,0 +1 @@
+../../../asset/favicon.png

doc/assets/images/favicon.png

@@ -0,0 +1 @@
+../../../asset/scheme.png

doc/assets/images/scheme.png

@@ -0,0 +1,23 @@
+.hide-in-mkdocs {
+    display: none;
+}
+
+.md-header__title {
+    margin-left: 0 !important;
+}
+
+[data-md-color-scheme="slate"] {
+    --md-code-fg-color: #ffffff;
+    --md-code-bg-color: #333542;
+}
+
+[data-md-color-scheme="default"] {
+    --md-code-bg-color: #ECEFF1;
+}
+
+.md-typeset code {
+    padding: 0.2em 0.4em;
+    border-radius: 4px;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}