migrate docs from Sphinx & GetText to material for MkDocs

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+# build docs from docstrings and markdown-file in folder docs
+# publish them as github pages
+#
+#note for myself
+#
+# Do not forget to set git branch `gh-pages` as source for github pages.
+# This branch auto-updated by `mkdocs gh-deploy`
+#
+name: docs
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    env:
+      PRIMARY_PYTHON_VERSION: '3.12'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PRIMARY_PYTHON_VERSION  }}
+      - run: |
+          pip install uv
+          uv pip install ghp-import -r docs/requirements.txt --python=${{ env.PRIMARY_PYTHON_VERSION }}
+      - run: ./scripts/build-docs.sh
+      - run: |
+          ghp-import --no-jekyll --push --force site

.gitignore

@@ -20,3 +20,7 @@ test_speed
 make_unidata
 project1
 test1
+**/venv/
+site/
+docs/_mkdocs.yml
+

docs/Makefile

@@ -1,20 +1,24 @@
-# Minimal makefile for Sphinx documentation
-#
+#!make
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = tregexpr
-SOURCEDIR     = .
-BUILDDIR      = _build
+.PHONY: en # mark as phony so it always runs even we have a docs folder
+.HELP: en  ## Docs preview English
+en:
+# 	docstrings.sh
+	open -a "Google Chrome" http://127.0.0.1:8000/TRegExpr/
+	sed "s/LANG_PLACEHOLDER/en/g" mkdocs.yml > _mkdocs.yml
+	mkdocs serve -f _mkdocs.yml
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
+.PHONY: ru # mark as phony so it always runs even we have a docs folder
+.HELP: ru  ## Docs preview Russian
+ru:
+# 	docstrings.sh
+	open -a "Google Chrome" http://127.0.0.1:8000/TRegExpr/
+	sed "s/LANG_PLACEHOLDER/en/g" mkdocs.yml > _mkdocs.yml
+	mkdocs serve -f _mkdocs.yml
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.HELP: help  ## Display this message
+help:
+	@grep -E \
+		'^.HELP: .*?## .*$$' $(MAKEFILE_LIST) | \
+		sort | \
+		awk 'BEGIN {FS = ".HELP: |## "}; {printf "\033[36m%-19s\033[0m %s\n", $$2, $$3}'

docs/adjust-rst.py

@@ -0,0 +1,38 @@
+"""Adjust RST before conversion to markdown.
+
+Fix the headers and anchors in the RST file to make it compatible with the pandoc conversion.
+"""
+import re
+import sys
+
+
+def adjust_rst(rst_file):
+    with open(rst_file, 'r', encoding='utf-8') as file:
+        lines = file.readlines()
+
+    # Regular expression to find header lines followed by underline markers
+    header_regex = re.compile(r'^(.*?)\n([-=~])\2{2,}\n', re.MULTILINE)
+    # Regular expression to find RST anchors
+    anchor_regex = re.compile(r'\.\.\s+_(\w+):')
+
+    def header_replacement(match):
+        text = match.group(1)
+        marker = match.group(2)[0] * len(text)  # Use the first character of the marker
+        return f"{text}\n{marker}\n"
+
+    content = header_regex.sub(header_replacement, ''.join(lines))
+
+    def anchor_replacement(match):
+        return f'<a name="{match.group(1)}"></a>'
+
+    new_content = anchor_regex.sub(anchor_replacement, content)
+
+    with open(rst_file, 'w', encoding='utf-8') as file:
+        file.write(new_content)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python adjust_rst_headers.py <path/to/input.rst>")
+        sys.exit(1)
+    adjust_rst(sys.argv[1])

docs/bg/demos.md

@@ -0,0 +1,71 @@
+|     |         |                                                                |                                                                |                                                                  |                                                                 |                                                                |
+|-----|---------|----------------------------------------------------------------|----------------------------------------------------------------|------------------------------------------------------------------|-----------------------------------------------------------------|----------------------------------------------------------------|
+|     | English | [Русский](https://regex.sorokin.engineer/ru/latest/demos.html) | [Deutsch](https://regex.sorokin.engineer/de/latest/demos.html) | [Български](https://regex.sorokin.engineer/bg/latest/demos.html) | [Français](https://regex.sorokin.engineer/fr/latest/demos.html) | [Español](https://regex.sorokin.engineer/es/latest/demos.html) |
+
+# Демонстрации
+
+Демо код за [TRegExpr](index.html)
+
+## Въведение
+
+If you don't familiar with regular expression, please, take a look at
+the [r.e.syntax](regular_expressions.html).
+
+TRegExpr interface described in [TRegExpr interface](tregexpr.html).
+
+## Text2HTML
+
+Източници Text2HTML
+\<<https://github.com/andgineer/TRegExpr/tree/master/examples/Text2HTML>\>\`\_
+
+Публикувайте обикновен текст като HTML
+
+Uses unit
+[HyperLinksDecorator](https://github.com/andgineer/TRegExpr/blob/master/src/HyperLinksDecorator.pas)
+that is based on TRegExpr.   Тази единица съдържа функции за декориране
+на хипер-връзки.
+
+For example, replaces `www.masterAndrey.com` with
+`<a href="http://www.masterAndrey.com">www.masterAndrey.com</a>` or
+`[email protected]` with
+`<a href="mailto:[email protected]">[email protected]</a>`.   ..
+code-block:: pascal
+
+> function DecorateURLs (  
+> const AText : string; AFlags : TDecorateURLsFlagSet = \[durlAddr,
+> durlPath\]
+>
+> ) : string;
+>
+> type TDecorateURLsFlags = ( durlProto, durlAddr, durlPort, durlPath,
+> durlBMark, durlParam);
+>
+> TDecorateURLsFlagSet = set of TDecorateURLsFlags;
+>
+> function DecorateEMails (const AText : string) : string;  
+
+| стойност   | значение                                                     |
+|------------|--------------------------------------------------------------|
+| durlProto  | Протокол (като `ftp: //` или `http: //`)                     |
+| durlAddr   | TCP адрес или име на домейн (като `masterAndrey.com`)        |
+| durlPort   | Номер на порт, ако е посочен (като &quot;: 8080&quot;)       |
+| durlPath   | Път до документа (като ,, index.html &quot;)                 |
+| durlBMark  | Маркиране на книга (като \`\` \# знак &#39;&#39;)            |
+| durlParam  | URL адреси (като &quot;? ID = 2 &amp; Потребител = 13&quot;) |
+
+Връща входния текст `AText` с украсени хипервръзки.
+
+`AFlags` describes, which parts of hyper-link must be included into
+visible part of the link.
+
+For example, if <span class="title-ref">AFlags</span> is `[durlAddr]`
+then hyper link `www.masterAndrey.com/contacts.htm` will be decorated as
+`<a href="www.masterAndrey.com/contacts.htm">www.masterAndrey.com</a>`.
+
+## [TRegExprRoutines](https://github.com/andgineer/TRegExpr/tree/master/examples/TRegExprRoutines)
+
+Много прости примери, вижте коментарите вътре в устройството
+
+## [TRegExprClass](https://github.com/andgineer/TRegExpr/tree/master/examples/TRegExprClass)
+
+Малко по-сложни примери, вижте коментарите вътре в устройството