docs: changes for scripts.

Author: Zuhaitz-dev

.github/workflows/docs-qa.yml

@@ -0,0 +1,41 @@
+name: Docs QA
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-qa.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+
+jobs:
+  check-code-examples:
+    name: Verify Code Examples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install Zen C Compiler
+        run: |
+          git clone --depth 1 https://github.com/zenc-lang/zenc.git /tmp/zenc-build
+          cd /tmp/zenc-build
+          sudo apt-get update && sudo apt-get install -y libtcc-dev
+          make -j$(nproc)
+          sudo make install
+          cd -
+      
+      - name: Run Code Example Checker
+        run: |
+          python3 docs/scripts/check_doc_examples.py docs/reference/*.md docs/std/*.md
+
+  check-translations:
+    name: Translation Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Check Translation Gaps
+        run: |
+          python3 docs/scripts/check_translations.py docs/reference docs/std

scripts/check_doc_examples.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Extract Zen C code examples from markdown files and compile them.
+Reports any compilation errors without blocking deployment.
+
+Usage:
+    python3 check_doc_examples.py docs/reference/*.md docs/std/*.md
+"""
+
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import glob
+
+ZC_BINARY = "./zc"  # Path to the Zen C compiler
+
+def find_zc():
+    """Find the zc binary in common locations."""
+    candidates = [
+        "./zc",
+        "../zc",
+        "/usr/local/bin/zc",
+        os.path.expanduser("~/zc"),
+    ]
+    for c in candidates:
+        if os.path.isfile(c) and os.access(c, os.X_OK):
+            return os.path.abspath(c)
+    return None
+
+def extract_code_blocks(filepath):
+    """Extract Zen C code blocks from a markdown file.
+    Yields (lineno, code) tuples for each ```zc block found.
+    """
+    zc_blocks = []
+    with open(filepath, 'r', encoding='utf-8') as f:
+        lines = f.readlines()
+    
+    in_block = False
+    block_start = 0
+    code_lines = []
+    
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith('```') and not in_block:
+            lang = stripped[3:].strip()
+            if lang in ('zc', 'zenc', ''):
+                # Check if next lines look like Zen C
+                in_block = True
+                block_start = i + 2  # 1-indexed, 1-based
+                code_lines = []
+        elif stripped.startswith('```') and in_block:
+            code = ''.join(code_lines)
+            if code.strip():
+                yield (block_start, code.strip())
+            in_block = False
+            code_lines = []
+        elif in_block:
+            code_lines.append(line)
+
+def compile_code(code, file_hint="example"):
+    """Try to compile a Zen C code snippet.
+    Returns (success, output) tuple.
+    """
+    zc = find_zc()
+    if not zc:
+        return (False, "zc compiler not found")
+    
+    # Wrap in a test if it looks like a snippet (no test/fn at top level)
+    # Simple heuristic: if it doesn't have 'fn ' or 'test ' at top level, wrap it
+    lines = code.strip().split('\n')
+    has_fn = any(l.strip().startswith('fn ') for l in lines)
+    has_test = any(l.strip().startswith('test ') for l in lines)
+    has_import = any(l.strip().startswith('import ') for l in lines)
+    
+    if not has_fn and not has_test and not has_import:
+        # It's probably a loose expression or statement — wrap in a test
+        code = f'test "doc_example" {{\n    {code.strip()}\n}}'
+    
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpfile = os.path.join(tmpdir, "example.zc")
+        with open(tmpfile, 'w') as f:
+            f.write(code)
+        
+        outfile = os.path.join(tmpdir, "example")
+        
+        try:
+            result = subprocess.run(
+                [zc, 'build', tmpfile, '-o', outfile],
+                capture_output=True, text=False, timeout=30
+            )
+            stderr = result.stderr.decode('utf-8', errors='replace')
+            if result.returncode != 0:
+                if "error:" in stderr:
+                    return (False, stderr[:500])
+                return (True, "")
+            return (True, "")
+        except subprocess.TimeoutExpired:
+            return (False, "Compilation timed out (30s)")
+        except FileNotFoundError:
+            return (False, f"Compiler not found: {zc}")
+
+def main():
+    files = sys.argv[1:] if len(sys.argv) > 1 else []
+    if not files:
+        # Default: scan all reference and std docs
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        docs_dir = os.path.join(script_dir, '..')
+        files = (glob.glob(os.path.join(docs_dir, 'reference/*.md')) +
+                 glob.glob(os.path.join(docs_dir, 'std/*.md')))
+        # Filter to only English originals (skip translations)
+        files = [f for f in files if not re.search(r'\.(de|es|it|pt|ru|zh-cn|zh-tw)\.md$', f)]
+    
+    zc = find_zc()
+    if not zc:
+        print("::warning::zc compiler not found — skipping code verification")
+        sys.exit(0)
+    
+    total = 0
+    failed = 0
+    skipped = 0
+    
+    for filepath in sorted(set(files)):
+        if not os.path.isfile(filepath):
+            continue
+        for lineno, code in extract_code_blocks(filepath):
+            total += 1
+            # Skip very long blocks (likely full programs with imports)
+            if len(code) > 2000:
+                skipped += 1
+                continue
+            
+            success, output = compile_code(code, filepath)
+            if not success:
+                relpath = os.path.relpath(filepath)
+                print(f"::error file={relpath},line={lineno}::Code example failed to compile")
+                print(f"  Code: {code[:100].strip()!r}...")
+                print(f"  Error: {output.strip()}")
+                failed += 1
+    
+    print(f"\nChecked {total} code blocks: {failed} failed, {skipped} skipped (too long)")
+    if failed > 0:
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

scripts/check_translations.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Check translation coverage across all languages.
+Reports missing files and aims for consistency.
+
+Usage:
+    python3 scripts/check_translations.py docs/reference docs/std
+"""
+
+import os
+import sys
+import re
+import glob
+from collections import defaultdict
+
+LANGUAGES = ['en', 'de', 'es', 'it', 'pt', 'ru', 'zh-cn', 'zh-tw']
+LANG_NAMES = {
+    'en': 'English', 'de': 'German', 'es': 'Spanish', 'it': 'Italian',
+    'pt': 'Portuguese', 'ru': 'Russian', 'zh-cn': 'Chinese (Simplified)',
+    'zh-tw': 'Chinese (Traditional)',
+}
+
+def get_lang(filename):
+    """Extract language suffix from a filename."""
+    base = os.path.basename(filename)
+    for lang in LANGUAGES:
+        if lang == 'en':
+            # English files have no language suffix
+            if not re.search(r'\.(de|es|it|pt|ru|zh-cn|zh-tw)\.', base):
+                return 'en'
+        else:
+            if f'.{lang}.' in base:
+                return lang
+    return None
+
+def analyze_directory(dirpath):
+    """Analyze a directory of translated documentation."""
+    files = glob.glob(os.path.join(dirpath, '*.md'))
+    
+    # Group by base name
+    groups = defaultdict(dict)
+    for f in files:
+        base = os.path.basename(f)
+        lang = get_lang(base)
+        if lang:
+            # Get the base name without language suffix
+            if lang == 'en':
+                stem = base
+            else:
+                stem = base.replace(f'.{lang}.md', '.md')
+            groups[stem][lang] = f
+    
+    return groups
+
+def report_directory(dirpath, name):
+    """Report translation status for a directory."""
+    groups = analyze_directory(dirpath)
+    
+    total = len(groups)
+    complete = 0
+    missing_any = 0
+    
+    for stem, langs in sorted(groups.items()):
+        missing = [l for l in LANGUAGES if l not in langs]
+        if not missing:
+            complete += 1
+        else:
+            missing_any += 1
+            if len(missing) <= 3:  # Only report if few missing
+                pass  # Report below
+    
+    print(f"\n## {name} ({total} documents)")
+    print(f"| Status | Count |")
+    print(f"|--------|-------|")
+    print(f"| Fully translated | {complete} |")
+    print(f"| Missing translations | {missing_any} |")
+    print()
+    
+    # Report specific gaps
+    for stem, langs in sorted(groups.items()):
+        missing = [l for l in LANGUAGES if l not in langs]
+        if missing:
+            english_file = langs.get('en', stem)
+            print(f"❌ **{stem}**: missing {', '.join(LANG_NAMES[l] for l in missing)}")
+    
+    # Report files that exist but weren't in the original English set
+    en_files = {stem for stem, langs in groups.items() if 'en' in langs}
+    non_en_only = {stem for stem, langs in groups.items() if 'en' not in langs}
+    if non_en_only:
+        for stem in sorted(non_en_only):
+            langs_present = ', '.join(LANG_NAMES[l] for l in groups[stem])
+            print(f"⚠️  **{stem}**: exists in {langs_present} but NOT in English")
+
+def main():
+    dirs = sys.argv[1:] if len(sys.argv) > 1 else []
+    if not dirs:
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        docs_dir = os.path.join(script_dir, '..')
+        dirs = [
+            os.path.join(docs_dir, 'reference'),
+            os.path.join(docs_dir, 'std'),
+        ]
+    
+    print("# Translation Coverage Report\n")
+    overall_complete = 0
+    overall_total = 0
+    
+    for d in dirs:
+        if os.path.isdir(d):
+            name = os.path.basename(d)
+            report_directory(d, name)
+    
+    print("\n---\n*Report generated by scripts/check_translations.py*")
+
+if __name__ == "__main__":
+    main()