Add [docs]: add doc for pybabel script

scripts/pybabel.py

@@ -10,14 +10,25 @@ import argparse
 import subprocess
 from pathlib import Path
 
+# Constant paths for project.
 LOCALES_DIR = Path("src/locales")
 LOCALES_DOMAIN = "messages"
 LOCALES_POT = LOCALES_DIR / f"{LOCALES_DOMAIN}.pot"
 LOCALES_WIDTH = 80
 
 
-def run_cmd(cmds: list[list[str]]) -> None:
+def run_commands(cmds: list[list[str]]) -> None:
+    """
+    Run terminal commands from Python.
+    Used for pybabel commands.
+
+    Args:
+        cmds (list[list[str]]): list of commands split by space.
+        Example: [["echo", "Hello World"], ["uv", "run", "main.py"]]
+    """
     try:
+        # Try to run command and print output.
+        # Print only stderr output (pybabel use stderr).
         for cmd in cmds:
             # DEBUG: User input is completely safe,
             # as it only accepts specific values.
@@ -34,6 +45,10 @@ def run_cmd(cmds: list[list[str]]) -> None:
 
 
 def main() -> None:
+    """
+    Main logic of script.
+    Parse args, try to run commands.
+    """
     parser = argparse.ArgumentParser(
         description="Wrapper for pybabel operations."
     )
@@ -65,20 +80,26 @@ def main() -> None:
     cmd.append("pybabel")
     cmd.append(args.operation)
 
+    # Extract operation require only extract command.
     if args.operation == "extract":
         cmd.append(".")
         cmd.append("-o")
         cmd.append(str(LOCALES_POT))
 
-        run_cmd([cmd])
+        run_commands([cmd])
         return
 
+    # Other operations (init, update, compile)
+    # may require multiple commands.
+
+    # Set base flags for these operations.
     cmd.append("-D")
     cmd.append(LOCALES_DOMAIN)
 
     cmd.append("-d")
     cmd.append(str(LOCALES_DIR))
 
+    # Specific flags
     if args.operation in ("update", "init"):
         cmd.append("-i")
         cmd.append(str(LOCALES_POT))
@@ -87,6 +108,7 @@ def main() -> None:
             cmd.append("-w")
             cmd.append(str(LOCALES_WIDTH))
 
+    # Add all langs or specific lang.
     if args.language == "all":
         langs = [
             str(path_name.name)
@@ -98,7 +120,8 @@ def main() -> None:
 
     cmds = [cmd + ["-l"] + [lang] for lang in langs]
 
-    run_cmd(cmds)
+    # Run commands
+    run_commands(cmds)
 
 
 if __name__ == "__main__":