fix: loosen parsing logic for options in code examples and warn on fix (#345)

Author: PLeVasseur

exts/coding_guidelines/common.py

@@ -1,4 +1,6 @@
 import logging
+import re
+from typing import Dict, List, Tuple
 
 from tqdm import tqdm
 
@@ -11,6 +13,64 @@ def get_tqdm(**kwargs):
     return tqdm(**kwargs)
 
 
+def sanitize_directive_content(content: str) -> Tuple[str, Dict[str, str], List[str]]:
+    """
+    Detect and extract RST directive options incorrectly included in code content.
+    
+    This handles cases where indentation issues in RST source files cause Sphinx's
+    directive parser to not recognize directive options, resulting in them appearing
+    in self.content instead of self.options.
+    
+    For example, if the RST has:
+        .. rust-example::
+            :version: 1.79
+            
+           use std::num::NonZero;  # <- Less indented than option!
+    
+    Sphinx will put ":version: 1.79" in content instead of options.
+    
+    Args:
+        content: The raw code content from a directive (joined self.content)
+        
+    Returns:
+        Tuple of (sanitized_code, extracted_options, raw_option_lines)
+        - sanitized_code: Code with option-like lines removed from the start
+        - extracted_options: Dict mapping option names to values
+        - raw_option_lines: The original lines that were extracted (for error messages)
+    """
+    lines = content.split('\n')
+    extracted_options: Dict[str, str] = {}
+    raw_option_lines: List[str] = []
+    code_start_idx = 0
+    
+    # Pattern to match directive options: :option_name: optional_value
+    # This matches the same format Sphinx expects for directive options
+    option_pattern = re.compile(r'^:(\w+):\s*(.*)$')
+    
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        
+        # Skip blank lines at the start (between options and code)
+        if not stripped:
+            code_start_idx = i + 1
+            continue
+        
+        # Check if this looks like a directive option
+        match = option_pattern.match(stripped)
+        if match:
+            opt_name = match.group(1)
+            opt_value = match.group(2).strip()
+            extracted_options[opt_name] = opt_value
+            raw_option_lines.append(stripped)
+            code_start_idx = i + 1
+        else:
+            # First non-option, non-blank line - actual code starts here
+            break
+    
+    sanitized_code = '\n'.join(lines[code_start_idx:])
+    return sanitized_code, extracted_options, raw_option_lines
+
+
 # Get the Sphinx logger
 logger = logging.getLogger("sphinx")
 logger.setLevel(logging.WARNING)

exts/coding_guidelines/rust_examples.py

@@ -41,7 +41,7 @@
 from sphinx.errors import SphinxError
 from sphinx.util import logging
 
-from .common import bar_format, get_tqdm
+from .common import bar_format, get_tqdm, sanitize_directive_content
 
 logger = logging.getLogger(__name__)
 
@@ -68,6 +68,13 @@ class MiriValidationError(SphinxError):
 # Warn mode values
 WARN_MODES = {"error", "allow"}  # error = fail on warnings (default), allow = permit warnings
 
+# Known directive options for rust-example (used for validation in sanitization)
+KNOWN_DIRECTIVE_OPTIONS = {
+    "ignore", "compile_fail", "should_panic", "no_run",
+    "miri", "warn", "edition", "channel", "version",
+    "show_hidden", "name"
+}
+
 
 class RustExamplesConfig:
     """Configuration loaded from rust_examples_config.toml"""
@@ -479,12 +486,53 @@ def run(self) -> List[nodes.Node]:
                 config = RustExamplesConfig()
             env.rust_examples_config = config
 
+        # Get source location early (needed for error messages)
+        source, line = self.state_machine.get_source_and_line(self.lineno)
+        
+        # Parse the code content
+        raw_code = '\n'.join(self.content)
+        
+        # Sanitize content - detect and extract misplaced directive options
+        # This handles RST indentation issues where Sphinx puts options into content
+        raw_code, extracted_options, raw_option_lines = sanitize_directive_content(raw_code)
+        
+        if extracted_options:
+            # Log a detailed warning about the indentation issue
+            opt_names = list(extracted_options.keys())
+            
+            # Build informative message with context
+            warning_parts = [
+                f"{source}:{line}: Found directive options in code content "
+                f"(RST indentation issue): {opt_names}.",
+                "These options were extracted and will be applied, but please fix the source file.",
+                "The code content should be indented at least as much as the options."
+            ]
+            
+            # Add specific context for version-related options
+            if 'version' in extracted_options:
+                extracted_version = extracted_options['version']
+                warning_parts.append(
+                    f"Note: Extracted :version: {extracted_version} "
+                    f"(config default: {config.version}, "
+                    f"mismatch threshold: {config.version_mismatch_threshold} minor versions)"
+                )
+            
+            logger.warning(" ".join(warning_parts))
+            
+            # Merge extracted options into self.options
+            # Sphinx-parsed options take precedence (they were properly formatted)
+            for opt_name, opt_value in extracted_options.items():
+                if opt_name not in self.options:
+                    # Handle flag-style options (empty value means flag is set)
+                    if opt_name in ('ignore', 'no_run', 'show_hidden') and opt_value == '':
+                        self.options[opt_name] = None  # Flag style
+                    else:
+                        self.options[opt_name] = opt_value
+        
         # Get configuration for showing hidden lines
         show_hidden_global = getattr(env.config, 'rust_examples_show_hidden', False)
         show_hidden = 'show_hidden' in self.options or show_hidden_global
 
-        # Parse the code content
-        raw_code = '\n'.join(self.content)
         display_code, full_code, hidden_line_numbers = process_hidden_lines(raw_code, show_hidden)
 
         # Determine rustdoc attribute
@@ -509,9 +557,6 @@ def run(self) -> List[nodes.Node]:
         miri_pattern = None
         has_miri_option = 'miri' in self.options
 
-        # Store source location (needed for error messages)
-        source, line = self.state_machine.get_source_and_line(self.lineno)
-        
         if has_miri_option:
             miri_mode, miri_pattern = parse_miri_option(self.options.get('miri', ''))
 

src/coding-guidelines/expressions/gui_7y0GAMmtMhch.rst.inc

@@ -94,7 +94,7 @@
       in this compliant example because the result of the division expression is an unsigned integer type.
 
       .. rust-example::
-          :version: 1.79
+         :version: 1.79
 
          use std::num::NonZero;
 

src/coding-guidelines/expressions/gui_RHvQj8BHlz9b.rst.inc

@@ -151,7 +151,7 @@
         The use of this function is noncompliant because it does not detect out-of-range shifts.
 
           .. rust-example::
-              :version: 1.87
+             :version: 1.87
 
              fn main() {
                  let bits : u32 = 61;