docs readme

docs folder refactored
andgineer · Mar 13, 2024 · 92329b3 · 92329b3
1 parent 6a17328
commit 92329b3
Show file tree

Hide file tree

Showing 39 changed files with 57 additions and 41 deletions.
diff --git a/docs/README.md b/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.
diff --git a/docs/adjust-rst.py b/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

diff --git a/docs/build-docs.sh b/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

diff --git a/docs/docs-render-config.sh b/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
diff --git a/docs/docstrings.sh b/docs/docstrings.sh
diff --git a/docs/fix_folder_redirects.py b/docs/fix_folder_redirects.py
@@ -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

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -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:

diff --git a/docs/bg/demos.md → docs/src/bg/demos.md b/docs/bg/demos.md → docs/src/bg/demos.md
diff --git a/docs/bg/faq.md → docs/src/bg/faq.md b/docs/bg/faq.md → docs/src/bg/faq.md
diff --git a/docs/bg/index.md → docs/src/bg/index.md b/docs/bg/index.md → docs/src/bg/index.md
diff --git a/docs/bg/regular_expressions.md → docs/src/bg/regular_expressions.md b/docs/bg/regular_expressions.md → docs/src/bg/regular_expressions.md
diff --git a/docs/bg/tregexpr.md → docs/src/bg/tregexpr.md b/docs/bg/tregexpr.md → docs/src/bg/tregexpr.md
diff --git a/docs/de/demos.md → docs/src/de/demos.md b/docs/de/demos.md → docs/src/de/demos.md
diff --git a/docs/de/faq.md → docs/src/de/faq.md b/docs/de/faq.md → docs/src/de/faq.md
diff --git a/docs/de/index.md → docs/src/de/index.md b/docs/de/index.md → docs/src/de/index.md
diff --git a/docs/de/regular_expressions.md → docs/src/de/regular_expressions.md b/docs/de/regular_expressions.md → docs/src/de/regular_expressions.md
diff --git a/docs/de/tregexpr.md → docs/src/de/tregexpr.md b/docs/de/tregexpr.md → docs/src/de/tregexpr.md
diff --git a/docs/en/demos.md → docs/src/en/demos.md b/docs/en/demos.md → docs/src/en/demos.md
diff --git a/docs/en/faq.md → docs/src/en/faq.md b/docs/en/faq.md → docs/src/en/faq.md
diff --git a/docs/en/index.md → docs/src/en/index.md b/docs/en/index.md → docs/src/en/index.md
diff --git a/docs/en/regular_expressions.md → docs/src/en/regular_expressions.md b/docs/en/regular_expressions.md → docs/src/en/regular_expressions.md
diff --git a/docs/en/tregexpr.md → docs/src/en/tregexpr.md b/docs/en/tregexpr.md → docs/src/en/tregexpr.md
diff --git a/docs/es/demos.md → docs/src/es/demos.md b/docs/es/demos.md → docs/src/es/demos.md
diff --git a/docs/es/faq.md → docs/src/es/faq.md b/docs/es/faq.md → docs/src/es/faq.md
diff --git a/docs/es/index.md → docs/src/es/index.md b/docs/es/index.md → docs/src/es/index.md
diff --git a/docs/es/regular_expressions.md → docs/src/es/regular_expressions.md b/docs/es/regular_expressions.md → docs/src/es/regular_expressions.md
diff --git a/docs/es/tregexpr.md → docs/src/es/tregexpr.md b/docs/es/tregexpr.md → docs/src/es/tregexpr.md
diff --git a/docs/fr/demos.md → docs/src/fr/demos.md b/docs/fr/demos.md → docs/src/fr/demos.md
diff --git a/docs/fr/faq.md → docs/src/fr/faq.md b/docs/fr/faq.md → docs/src/fr/faq.md
diff --git a/docs/fr/index.md → docs/src/fr/index.md b/docs/fr/index.md → docs/src/fr/index.md
diff --git a/docs/fr/regular_expressions.md → docs/src/fr/regular_expressions.md b/docs/fr/regular_expressions.md → docs/src/fr/regular_expressions.md
diff --git a/docs/fr/tregexpr.md → docs/src/fr/tregexpr.md b/docs/fr/tregexpr.md → docs/src/fr/tregexpr.md
diff --git a/docs/ru/demos.md → docs/src/ru/demos.md b/docs/ru/demos.md → docs/src/ru/demos.md
diff --git a/docs/ru/faq.md → docs/src/ru/faq.md b/docs/ru/faq.md → docs/src/ru/faq.md
diff --git a/docs/ru/index.md → docs/src/ru/index.md b/docs/ru/index.md → docs/src/ru/index.md
diff --git a/docs/ru/regular_expressions.md → docs/src/ru/regular_expressions.md b/docs/ru/regular_expressions.md → docs/src/ru/regular_expressions.md
@@ -2,11 +2,8 @@
 
 ## Вступление
 
-Regular expressions are a handy way to specify patterns of text.
-
-With regular expressions you can validate user input, search for some
-patterns like emails of phone numbers on web pages or in some documents
-and so on.
+Регулярные выражения являются простым и мощным инструментом для сложного 
+поиска и замены, а также для проверки текста на основе шаблонов.
 
 Ниже приведена исчерпывающая шпаргалка по регулярных выражениям всего на
 одной странице.

diff --git a/docs/ru/tregexpr.md → docs/src/ru/tregexpr.md b/docs/ru/tregexpr.md → docs/src/ru/tregexpr.md
diff --git a/docs/to-md.sh b/docs/to-md.sh
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 #
 # Convert .rst files to GitHub-style .md
+# Used for migration from Sphinx & gettext to MkDocs
 #
 for lang in bg de en es fr ru; do
     find "$lang" -name "*.rst" -type f -exec sh -c '

diff --git a/docs/translate_rst.py b/docs/translate_rst.py
@@ -1,15 +1,6 @@
-"""Translate the RST files using the PO files from GetText.
+"""Translate the .rst files using the .po files (GetText).
 
-I decided no longer fight with over-complicated WebLate translations and 
-make a big leap of faith to get rid of GetText translation.
-
-After all it's not intended to be used for RST files and it's a pain to maintain.
-
-Good reasoning here
-https://github.com/natcap/invest.users-guide/issues/54
- 
-I will use this script to apply translations to the RST files and from that point
-no .po files, just rst files for each translation.
+Used for migration from Spinx/rst & gettext to plain rst-files.
 """
 import polib
 import os