Update documentation ensuring selected codes

Author: johnsamuelwrites

_scripts/compile_blocks.py

@@ -32,13 +32,38 @@
 # Languages that never receive a Run button (matches NON_EXECUTABLE in main.js)
 NON_EXECUTABLE = {
     'bash', 'sh', 'shell', 'powershell', 'cmd',
+    'js', 'javascript', 'markdown', 'dockerfile',
     'yaml', 'toml', 'json', 'plaintext', 'text', 'output', 'wat', 'rust',
     '',
 }
 
 BLOCKS_DIR = Path('assets/wasm/blocks')
 TIMEOUT    = 60   # seconds per block compilation
 
+HOST_PY_RE = re.compile(
+    r'^\s*(import\s+[\w.]+|from\s+[\w.]+\s+import\s+|#!/usr/bin/env\s+python\d*(?:\.\d+)*)',
+    re.MULTILINE,
+)
+PYTHON_API_RE = re.compile(
+    r'executor\.|BackendSelector\(\)|NumeralConverter\(\)|ProgramExecutor\(\)'
+    r'|wasm_gen\.|sel\.|Lexer\(language=|Parser\(language='
+    r'|SemanticAnalyzer\(|ASTPrinter\(\)|\.generate_rust\('
+)
+WASM_UNSUPPORTED_RE = re.compile(
+    r'\byield\b'                        # generators / yield from
+    r'|^\s*match\s+\S'                 # structural pattern matching
+    r'|:='                              # walrus operator
+    r'|^\s*@\w'                         # function / class decorators
+    r'|\blambda\b'                      # lambda expressions
+    r'|\*\*\w+'                         # **kwargs double-star arg
+    r'|(?:,|\()\s*\*[a-zA-Z]'          # *args single-star arg
+    r'|(?:,|\()\s*\*\s*,'              # keyword-only * separator  (def f(a, *, b))
+    r'|(?:,|\()\s*/\s*[,)]'            # positional-only / sep    (def f(a, b, /))
+    r'|\bnonlocal\b'                    # nonlocal (closure)
+    r'|\basync\s+(?:def|for|with)\b',  # async / await constructs
+    re.MULTILINE,
+)
+
 
 def sha16(code: str) -> str:
     """First 16 hex chars of SHA-256(code), matching the browser SubtleCrypto hash."""
@@ -112,6 +137,13 @@ def main():
             if lang in NON_EXECUTABLE:
                 skipped += 1
                 continue
+            if lang == 'python' and (
+                HOST_PY_RE.search(code)
+                or PYTHON_API_RE.search(code)
+                or WASM_UNSUPPORTED_RE.search(code)
+            ):
+                skipped += 1
+                continue
             if 'print(' not in code:
                 skipped += 1
                 continue

_tests/test_code_blocks.py

@@ -29,6 +29,7 @@
 
 NON_EXECUTABLE = {
     'bash', 'sh', 'shell', 'powershell', 'cmd',
+    'js', 'javascript', 'markdown', 'dockerfile',
     'yaml', 'toml', 'json', 'plaintext', 'text',
     'output', 'wat', 'rust',
     '',
@@ -40,6 +41,36 @@
 VALIDATE_TIMEOUT = 10  # seconds — wasm-validate
 EXECUTE_TIMEOUT  = 10  # seconds — __main() wall-clock guard
 
+# Blocks that contain any of these patterns are host-Python integration code
+# (multilingualprogramming API usage, test harnesses, diagnostic scripts) —
+# not standalone multilingual programs that can be compiled to WASM.
+HOST_PY_RE = re.compile(
+    r'^\s*(import\s+[\w.]+|from\s+[\w.]+\s+import\s+|#!/usr/bin/env\s+python\d*(?:\.\d+)*)',
+    re.MULTILINE,
+)
+# Catches orphan API blocks whose `from ... import` lives in a prior block.
+PYTHON_API_RE = re.compile(
+    r'executor\.|BackendSelector\(\)|NumeralConverter\(\)|ProgramExecutor\(\)'
+    r'|wasm_gen\.|sel\.|Lexer\(language=|Parser\(language='
+    r'|SemanticAnalyzer\(|ASTPrinter\(\)|\.generate_rust\('
+)
+# Patterns for syntax that WATCodeGenerator does not yet support.
+# Remove entries here as the compiler gains support for each feature.
+WASM_UNSUPPORTED_RE = re.compile(
+    r'\byield\b'                        # generators / yield from
+    r'|^\s*match\s+\S'                 # structural pattern matching
+    r'|:='                              # walrus operator
+    r'|^\s*@\w'                         # function / class decorators
+    r'|\blambda\b'                      # lambda expressions
+    r'|\*\*\w+'                         # **kwargs double-star arg
+    r'|(?:,|\()\s*\*[a-zA-Z]'          # *args single-star arg
+    r'|(?:,|\()\s*\*\s*,'              # keyword-only * separator  (def f(a, *, b))
+    r'|(?:,|\()\s*/\s*[,)]'            # positional-only / sep    (def f(a, b, /))
+    r'|\bnonlocal\b'                    # nonlocal (closure)
+    r'|\basync\s+(?:def|for|with)\b',  # async / await constructs
+    re.MULTILINE,
+)
+
 
 # ---------------------------------------------------------------------------
 # Block collection
@@ -50,9 +81,9 @@ def _collect_blocks():
     Yield pytest.param(code, id=...) for every executable fenced code block
     found in the docs markdown files.
 
-    A block is included when its language tag is NOT in NON_EXECUTABLE.
-    Unlike compile_blocks.py we do NOT filter on `print(` — we want to test
-    every block that the docs present to readers as executable.
+    A block is included when its language tag is NOT in NON_EXECUTABLE, its
+    content is not host-Python integration/setup code, and it contains at
+    least one `print(` call (matching compile_blocks.py).
     """
     pattern = re.compile(r'^```(\w*)\n(.*?)^```', re.MULTILINE | re.DOTALL)
 
@@ -69,6 +100,14 @@ def _collect_blocks():
             code = m.group(2).strip()
             if lang in NON_EXECUTABLE or not code:
                 continue
+            if lang == 'python' and (
+                HOST_PY_RE.search(code)
+                or PYTHON_API_RE.search(code)
+                or WASM_UNSUPPORTED_RE.search(code)
+            ):
+                continue
+            if 'print(' not in code:
+                continue
             yield pytest.param(code, id=f'{rel}::block-{idx}')
 
 

assets/js/main.js

@@ -170,6 +170,8 @@
   const NON_EXECUTABLE = new Set([
     'language-bash', 'language-sh', 'language-shell',
     'language-powershell', 'language-cmd',
+    'language-js', 'language-javascript', 'language-markdown', 'language-dockerfile',
+    'language-output', 'language-wat', 'language-rust',
     'language-yaml', 'language-toml', 'language-json',
     'language-plaintext', 'language-text',
   ]);
@@ -178,6 +180,10 @@
     return [...codeEl.classList].every(c => !NON_EXECUTABLE.has(c));
   }
 
+  function looksLikeHostPython(src) {
+    return /^\s*(import\s+\w+|from\s+\w+\s+import\s+|#!\/usr\/bin\/env\s+python\d*(?:\.\d+)*)/m.test(src);
+  }
+
   /* Render output (stdout + optional stderr) into a .code-output element. */
   function renderOutput(container, { stdout, stderr }) {
     container.innerHTML = '';
@@ -309,6 +315,7 @@
   document.querySelectorAll('.content-body pre').forEach(pre => {
     const code = pre.querySelector('code');
     if (!code || !isExecutable(code)) return;
+    if (code.classList.contains('language-python') && looksLikeHostPython(code.textContent || '')) return;
 
     /* Output panel inserted after <pre>. */
     const outputPanel = document.createElement('div');

design/stdlib-localization.md

@@ -45,7 +45,7 @@ multilingual distinguishes three layers of localization:
 
 Grammar-level keywords are mapped via the Universal Semantic Model (USM). Every supported language has its own surface form for `COND_IF`, `LOOP_FOR`, `FUNC_DEF`, and all 51 semantic concepts.
 
-```python
+```plaintext
 # English
 if x > 0:
     print(x)
@@ -63,7 +63,7 @@ si x > 0:
 
 Selected built-in functions support localized **aliases**. The canonical English name is always available; aliases are additive:
 
-```python
+```plaintext
 # English universal name — works in any language
 print(range(5))
 len([1, 2, 3])

reference/builtins.md

@@ -18,7 +18,7 @@ multilingual provides localized aliases for 41 commonly used Python built-in fun
 
 ## Using Built-in Aliases
 
-```python
+```plaintext
 # In English — universal name works
 print(range(5))
 print(len([1, 2, 3]))

wasm/development.md

@@ -20,7 +20,7 @@ This guide covers writing WASM-compatible multilingual programs and contributing
 
 All multilingual programs are automatically compatible with both Python and WASM backends. The backend selection is transparent.
 
-```python
+```plaintext
 # This program runs on Python or WASM automatically
 let matrix_a = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
 let matrix_b = [[9, 8, 7], [6, 5, 4], [3, 2, 1]]
@@ -45,7 +45,7 @@ let transposed = matrix_transpose(matrix)
 
 #### 2. Numeric-Intensive Loops
 
-```python
+```plaintext
 # Scientific computation — WASM excels here
 def monte_carlo_pi(samples):
     let inside = 0