Changes to the build scripts

Author: braboj

.scripts/acronyms.json

@@ -0,0 +1,37 @@
+{
+  "AI": "Artificial Intelligence",
+  "API": "Application Programming Interface",
+  "CI": "Continuous Integration",
+  "CD": "Continuous Delivery",
+  "CPU": "Central Processing Unit",
+  "CSS": "Cascading Style Sheets",
+  "DB": "Database",
+  "DBMS": "Database Management System",
+  "DNS": "Domain Name System",
+  "DOM": "Document Object Model",
+  "DRY": "Don't Repeat Yourself",
+  "FTP": "File Transfer Protocol",
+  "FOSS": "Free and Open Source Software",
+  "GPU": "Graphics Processing Unit",
+  "GUI": "Graphical User Interface",
+  "HTML": "HyperText Markup Language",
+  "HTTP": "HyperText Transfer Protocol",
+  "IDE": "Integrated Development Environment",
+  "I/O": "Input/Output",
+  "IP": "Internet Protocol",
+  "JSON": "JavaScript Object Notation",
+  "MVC": "Model View Controller",
+  "OOP": "Object Oriented Programming",
+  "ORM": "Object Relational Mapping",
+  "OS": "Operating System",
+  "RAM": "Random Access Memory",
+  "REST": "Representational State Transfer",
+  "SOLID": "Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion",
+  "SDK": "Software Development Kit",
+  "SQL": "Structured Query Language",
+  "UI": "User Interface",
+  "URL": "Uniform Resource Locator",
+  "UX": "User Experience",
+  "VM": "Virtual Machine",
+  "XML": "eXtensible Markup Language"
+}

.scripts/gen_markdown_chapters.py

@@ -14,26 +14,46 @@
 """
 
 import argparse
+import json
 import re
 from pathlib import Path
 
-
-
 def to_title(name: str) -> str:
     """Return *name* in title format with spaces and preserved acronyms."""
+
     # Remove numeric prefixes like ``01_``
     name = re.sub(r"^\d+[_-]?", "", name)
+
+    # Split on underscores, dashes, or spaces
     parts = re.split(r"[_\-\s]+", name)
+
+    # Import JSON file containing user-defined acronyms
+    with open('acronyms.json') as json_data:
+        user_acronyms = json.load(json_data)
+
+    # Capitalize each part, preserving all-uppercase acronyms
     words = []
     for part in parts:
+
+        print(part)
+
+        # Skip empty parts that may result from leading/trailing separators
         if not part:
             continue
-        if re.fullmatch(r"[A-Z0-9]+", part):
-            words.append(part)
-        elif re.fullmatch(r"[a-z]+", part) and len(part) <= 4:
+
+        # Check user-defined acronyms from `docs/acronyms.txt`
+        if part.upper() in user_acronyms:
             words.append(part.upper())
+
+        # If the part is all uppercase and contains only alphanumeric characters,
+        # treat it as an acronym and keep it as is
+        elif re.fullmatch(r"[A-Z0-9]+", part):
+            words.append(part)
+
+        # Otherwise, capitalize the first letter and lowercase the rest
         else:
             words.append(part.capitalize())
+
     return " ".join(words)
 
 
@@ -83,7 +103,7 @@ def main() -> None:
     )
     parser.add_argument(
         "--output-dir",
-        default="../docs",
+        default="../docs/examples",
         help="Directory where Markdown files will be written",
     )
     args = parser.parse_args()

.scripts/gen_markdown_pages.py

@@ -54,17 +54,17 @@ def main() -> None:
     )
     parser.add_argument(
         "--examples-dir",
-        default="examples",
+        default="../examples",
         help="Directory containing example .py files",
     )
     parser.add_argument(
         "--template",
-        default="templates/example_file.mustache",
+        default="../templates/example_file.mustache",
         help="Mustache template file",
     )
     parser.add_argument(
         "--output-dir",
-        default="docs",
+        default="../docs",
         help="Directory where Markdown files will be written",
     )
     args = parser.parse_args()

.scripts/gen_single_markdown.py

@@ -57,17 +57,17 @@ def main() -> None:
     parser = argparse.ArgumentParser(description="Generate examples markdown")
     parser.add_argument(
         "--examples-dir",
-        default="examples",
+        default="../examples",
         help="Directory containing example .py files",
     )
     parser.add_argument(
         "--template",
-        default="templates/examples_page.mustache",
+        default="../templates/examples_page.mustache",
         help="Mustache template file",
     )
     parser.add_argument(
         "--output",
-        default="examples.md",
+        default="../docs/examples.md",
         help="Output markdown file",
     )
     args = parser.parse_args()