Generated description for every helper file

.gitea/workflows/helpers/class-comment.py

@@ -1,5 +1,18 @@
 #!/usr/bin/env python3
-"""Generate PR comment from CLASS.TXT.json violations."""
+"""
+Generate PR comment for CLASS.TXT.json duplicate title violations.
+
+This script reads violations.json (created by class-txt-check.py) and generates
+a formatted markdown comment to be posted on the PR. The comment includes:
+  - File path where violations were found
+  - Parent document title and code
+  - The duplicate title
+  - Document codes that share the duplicate title
+
+Usage:
+  Run after class-txt-check.py fails. Reads violations.json and outputs JSON
+  with 'body' field containing the markdown comment text.
+"""
 
 import json
 import sys

.gitea/workflows/helpers/class-txt-check.py

@@ -1,5 +1,26 @@
 #!/usr/bin/env python3
-"""Check CLASS.TXT.json files for duplicate titles under the same parent."""
+"""
+Check CLASS.TXT.json files for duplicate titles under the same parent document.
+
+This script validates that child documents under the same parent (p_code) have
+unique titles. Comparison is case-insensitive, so "Creating an ECS" and
+"creating an ecs" are considered duplicates.
+
+JSON structure:
+  - Each entry has: code (document ID), p_code (parent document ID), title
+  - Documents with same p_code are siblings under the same parent
+  - Siblings must have unique titles (case-insensitive)
+
+Example violation:
+  Parent (code="3", title="Virtual Private Cloud")
+    - Child (code="4", p_code="3", title="Creating a VPC")
+    - Child (code="5", p_code="3", title="creating a vpc")  <- DUPLICATE!
+
+Usage:
+  Set CHANGED_FILES environment variable with space-separated list of CLASS.TXT.json files.
+  Exits with code 1 if violations found, 0 otherwise.
+  Writes violations to violations.json for comment generation.
+"""
 
 import sys
 import os

.gitea/workflows/helpers/metadata-check.py

@@ -1,5 +1,30 @@
 #!/usr/bin/env python3
-"""Check that newly added HTML files are registered in metadata files."""
+"""
+Check that newly added HTML files are registered in both metadata files.
+
+This script validates that every new HTML file added in a PR is properly
+registered in both CLASS.TXT.json and ALL_META.TXT.json in the same directory.
+
+Directory structure:
+  docs/vpc/api-ref/
+  ├── CLASS.TXT.json      # Contains uri references to HTML files
+  ├── ALL_META.TXT.json   # Contains uri references to HTML files
+  └── en-us_topic_XXXXX.html
+
+Both metadata files use the "uri" field to reference HTML filenames. When a
+new HTML file is added, it must be added to both metadata files.
+
+Checks performed:
+  1. Does CLASS.TXT.json exist in the HTML file's directory?
+  2. Does ALL_META.TXT.json exist in the HTML file's directory?
+  3. Is the HTML filename listed in CLASS.TXT.json (in uri field)?
+  4. Is the HTML filename listed in ALL_META.TXT.json (in uri field)?
+
+Usage:
+  Set ADDED_FILES environment variable with space-separated list of added HTML files.
+  Exits with code 1 if violations found, 0 otherwise.
+  Writes violations to violations.json for comment generation.
+"""
 
 import sys
 import os

.gitea/workflows/helpers/metadata-comment.py

@@ -1,5 +1,17 @@
 #!/usr/bin/env python3
-"""Generate PR comment from metadata check violations."""
+"""
+Generate PR comment for metadata registration check violations.
+
+This script reads violations.json (created by metadata-check.py) and generates
+a formatted markdown comment to be posted on the PR. The comment includes:
+  - HTML file path that was added but not registered
+  - Which metadata files it's missing from (CLASS.TXT.json, ALL_META.TXT.json)
+  - Whether the metadata files don't exist or the file is simply missing from them
+
+Usage:
+  Run after metadata-check.py fails. Reads violations.json and outputs JSON
+  with 'body' field containing the markdown comment text.
+"""
 
 import json
 import sys

.gitea/workflows/helpers/underscore-comment.py

@@ -1,24 +1,38 @@
 #!/usr/bin/env python3
-"""Generate PR comment from violations."""
+"""
+Generate PR comment for underscore check violations.
+
+This script reads violations.json (created by underscore-check.py) and generates
+a formatted markdown comment to be posted on the PR. The comment includes:
+  - File path where violations were found
+  - Line number of each violation
+  - The offending word (ending with underscore)
+  - Context showing where the violation appears in the HTML
+
+Usage:
+  Run after underscore-check.py fails. Reads violations.json and outputs JSON
+  with 'body' field containing the markdown comment text.
+"""
+
 import json
 import sys
 
 
 def main():
     try:
-        with open('violations.json', 'r') as f:
+        with open("violations.json", "r") as f:
             violations = json.load(f)
     except Exception:
         violations = []
 
     if not violations:
-        print(json.dumps({'body': 'No violations to report'}))
+        print(json.dumps({"body": "No violations to report"}))
         sys.exit(0)
 
     # Group violations by file
     by_file = {}
     for v in violations:
-        key = v['file']
+        key = v["file"]
         if key not in by_file:
             by_file[key] = []
         by_file[key].append(v)
@@ -28,25 +42,27 @@ def main():
         "❌ **Underscore check failed**",
         "",
         "Found words ending with underscore (not followed by alphanumeric characters):",
-        ""
+        "",
     ]
 
     for filepath, file_violations in by_file.items():
         lines.append(f"**{filepath}:**")
         for v in file_violations:
-            word = v['word']
-            line_num = v['line']
-            context = v['context']
+            word = v["word"]
+            line_num = v["line"]
+            context = v["context"]
             # Escape markdown special chars in context
-            context = context.replace('`', '\\`')
+            context = context.replace("`", "\\`")
             lines.append(f"   - Line {line_num}: `{word}` in context: `{context}`")
         lines.append("")
 
-    lines.append("**Please fix these issues as soon as possible.** Words should not end with an underscore unless followed by alphanumeric characters (A-Za-z0-9).")
+    lines.append(
+        "**Please fix these issues as soon as possible.** Words should not end with an underscore unless followed by alphanumeric characters (A-Za-z0-9)."
+    )
 
     message = "\n".join(lines)
-    print(json.dumps({'body': message}))
+    print(json.dumps({"body": message}))
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()