docs readme

docs folder refactored

Author: andgineer

docs/README.md

@@ -0,0 +1,32 @@
+# TRegExpr documentation compilation
+
+Sources from `docs/src/` are compiled by Github Action `docs` to `site/` using 
+[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+
+The English version (en) is placed at the root of the site, while other 
+languages, are placed in corresponding subdirectories. 
+Consequently, by default, the English version is served.
+
+The GitHub action is triggered by pushes to the `main` branch. 
+After compiling the docs to `site/`, it pushes them to the `gh-pages` branch. 
+The GitHub repository is configured to serve the gh-pages branch as a 
+website with the custom domain `regex.sorokin.engineer`.
+
+Use `make en` and similar commands to compile and debug the documentation locally. 
+To see all available commands, use `make help`.
+
+## A bit of history
+
+In March 2024, I decided to stop struggling with overly complicated [gettext](https://www.gnu.org/software/gettext/) 
+translations with WebLate and took a significant leap of faith to abandon gettext
+translations. 
+
+It's not meant for RST files, and maintaining it has been challenging.
+
+There's good reasoning for this decision outlined here:
+[Should we use gettext for RST files?](https://github.com/natcap/invest.users-guide/issues/54)
+
+Simultaneously, I opted to transition from Sphinx/RST to Markdown to simplify 
+things. 
+
+With `Material for MkDocs`, RST no longer presents any real advantages.

docs/adjust-rst.py

@@ -1,6 +1,7 @@
-"""Adjust RST before conversion to markdown.
+"""Adjust RST for Markdown conversion.
 
-Fix the headers and anchors in the RST file to make it compatible with the pandoc conversion.
+Fix headers and anchors for pandoc compatibility.
+Used for migration from Sphinx & gettext to MkDocs
 """
 import re
 import sys

docs/build-docs.sh

@@ -1,13 +1,13 @@
 #!/usr/bin/env bash
 #
-# Create docs in docs/
+# Render site/ from docs/src/
 #
 
-#./scripts/docstrings.sh
-
 for lang in en bg de es fr ru; do  # en should be the first language as it clears the root of the site
     ./docs-render-config.sh $lang
     mkdocs build --config-file _mkdocs.yml
+
+    # Additional redirects that is impossible to create with `mkdocs-redirects`
     if [ $lang = "en" ]; then
       mkdir -p ../site/en
       cp -r ../site/latest ../site/en/latest

docs/docs-render-config.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 #
-# Substitute language and site in mkdocs.yml in _mkdocs.yml
-# language should be passed as an argument
+# Copy mkdocs.yml to _mkdocs.yml with substitute language and site.
+# the language should be passed as an argument
+# Place CSS to appropriate docs/src/ folder.
 #
 
 lang=$1
@@ -13,4 +14,4 @@ if [ $lang = "en" ]; then
 else
     sed -i'' -e "s/SITE_PLACEHOLDER/$lang/g" _mkdocs.yml
 fi
-cp -r css $lang/_css/  # mkdocs expects css to be in the root of the docs folder
+cp -r css src/$lang/_css/  # mkdocs expects css to be in the root of the docs folder

docs/docstrings.sh

@@ -1,3 +1,12 @@
+"""File redirects instead of directory ones.
+
+`mkdocs-redirects` respects option `use_directory_urls`, which is set to True for more readable URLs,
+hence it generates folder URLs for both redirect sources and targets.
+
+However, our old site utilized file URLs, necessitating redirects from these old file URLs to the new folder URLs.
+
+This script generates file redirect sources for all the folder redirects created by mkdocs-redirects.
+"""
 import os
 import shutil
 import argparse

docs/fix_folder_redirects.py

@@ -7,7 +7,7 @@ site_author: Andrey Sorokin
 repo_name: TRegExpr
 repo_url: https://github.com/andgineer/TRegExpr
 edit_uri: edit/master/docs
-docs_dir: 'LANG_PLACEHOLDER'
+docs_dir: 'src/LANG_PLACEHOLDER'
 site_dir: '../site/SITE_PLACEHOLDER'
 
 extra_css: