rolfedh-doc-utils 0.1.29__py3-none-any.whl → 0.1.31__py3-none-any.whl

callout_lib/converter_bullets.py

@@ -16,7 +16,7 @@ class BulletListConverter:
     USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
 
     @staticmethod
-    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> List[str]:
+    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "") -> List[str]:
         """
         Create bulleted list from callout groups and explanations.
 
@@ -33,12 +33,20 @@ class BulletListConverter:
 
         Args:
             callout_groups: List of CalloutGroup objects from code block
+            table_title: Optional table title (e.g., ".Descriptions of delete event")
+                        Will be converted to lead-in sentence
             explanations: Dict mapping callout numbers to Callout objects
 
         Returns:
             List of strings representing the bulleted list
         """
-        lines = ['']  # Start with blank line before list
+        # Convert table title to lead-in sentence if present
+        if table_title:
+            # Remove leading dot and trailing period if present
+            title_text = table_title.lstrip('.').rstrip('.')
+            lines = [f'\n{title_text}:']  # Use colon for bulleted list lead-in
+        else:
+            lines = ['']  # Start with blank line before list
 
         # Process each group (which may contain one or more callouts)
         for group in callout_groups:

callout_lib/converter_deflist.py

@@ -16,7 +16,7 @@ class DefListConverter:
     USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
 
     @staticmethod
-    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> List[str]:
+    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "") -> List[str]:
         """
         Create definition list from callout groups and explanations.
 
@@ -29,11 +29,19 @@ class DefListConverter:
         Args:
             callout_groups: List of CalloutGroup objects from code block
             explanations: Dict mapping callout numbers to Callout objects
+            table_title: Optional table title (e.g., ".Descriptions of delete event")
+                        Will be converted to lead-in sentence (e.g., "Descriptions of delete event, where:")
 
         Returns:
             List of strings representing the definition list
         """
-        lines = ['\nwhere:']
+        # Convert table title to lead-in sentence if present
+        if table_title:
+            # Remove leading dot and trailing period if present
+            title_text = table_title.lstrip('.').rstrip('.')
+            lines = [f'\n{title_text}, where:']
+        else:
+            lines = ['\nwhere:']
 
         # Process each group (which may contain one or more callouts)
         for group in callout_groups:
@@ -70,10 +78,37 @@ class DefListConverter:
                     lines.append('+')
 
                 # Add explanation lines, prepending "Optional. " to first line if needed
+                # Handle blank lines and conditionals by inserting continuation markers
+                need_continuation = False
+                had_content = False  # Track if we've output any non-conditional content
+
                 for line_idx, line in enumerate(explanation.lines):
+                    stripped = line.strip()
+
+                    # Check if this is a blank line
+                    if stripped == '':
+                        # Next non-blank line will need a continuation marker
+                        need_continuation = True
+                        continue  # Skip blank lines
+
+                    # Check if this is a conditional directive
+                    is_conditional = stripped.startswith(('ifdef::', 'ifndef::', 'endif::'))
+
+                    # Add continuation marker if:
+                    # 1. Previous line was blank (need_continuation=True), OR
+                    # 2. This is a conditional and we've had content before (need separator)
+                    if need_continuation or (is_conditional and had_content and line_idx > 0):
+                        lines.append('+')
+                        need_continuation = False
+
+                    # Add the line
                     if line_idx == 0 and explanation.is_optional:
                         lines.append(f'Optional. {line}')
                     else:
                         lines.append(line)
 
+                    # Track that we've output content (not just conditionals)
+                    if not is_conditional:
+                        had_content = True
+
         return lines

callout_lib/detector.py

@@ -60,6 +60,8 @@ class CalloutDetector:
     def __init__(self):
         """Initialize detector with table parser."""
         self.table_parser = TableParser()
+        self.last_table_title = ""  # Track title from most recent table extraction
+        self.last_table = None  # Track last table found for validation diagnostics
 
     def find_code_blocks(self, lines: List[str]) -> List[CodeBlock]:
         """Find all code blocks in the document."""
@@ -181,17 +183,24 @@ class CalloutDetector:
 
     def _extract_from_table(self, table) -> Tuple[Dict[int, Callout], int]:
         """Extract callout explanations from a table format."""
+        # Store table for use by converters and validation
+        self.last_table = table
+        self.last_table_title = table.title if hasattr(table, 'title') else ""
+
         explanations = {}
         table_data = self.table_parser.extract_callout_explanations_from_table(table)
 
-        for callout_num, (explanation_lines, conditionals) in table_data.items():
-            # Combine explanation lines with conditionals preserved
+        for callout_num, (explanation_lines, row_conditionals) in table_data.items():
+            # explanation_lines now includes blank lines and conditionals inline
+            # row_conditionals are before/after the entire row (rarely used)
             all_lines = []
-            for line in explanation_lines:
-                all_lines.append(line)
 
-            # Add conditionals as separate lines (they'll be preserved in output)
-            all_lines.extend(conditionals)
+            # Add any row-level conditionals before
+            if row_conditionals:
+                all_lines.extend(row_conditionals)
+
+            # Add explanation lines (already includes inline conditionals and blank lines)
+            all_lines.extend(explanation_lines)
 
             # Check if marked as optional
             is_optional = False
@@ -212,14 +221,22 @@ class CalloutDetector:
         Extract callout explanations from a 3-column table format.
         Format: Item (number) | Value | Description
         """
+        # Store table for use by converters and validation
+        self.last_table = table
+        self.last_table_title = table.title if hasattr(table, 'title') else ""
+
         explanations = {}
         table_data = self.table_parser.extract_3column_callout_explanations(table)
 
-        for callout_num, (value_lines, description_lines, conditionals) in table_data.items():
+        for callout_num, (value_lines, description_lines, row_conditionals) in table_data.items():
             # Combine value and description into explanation lines
-            # Strategy: Include value as context, then description
+            # Both value_lines and description_lines now include conditionals and blank lines inline
             all_lines = []
 
+            # Add any row-level conditionals before
+            if row_conditionals:
+                all_lines.extend(row_conditionals)
+
             # Add value lines with context
             if value_lines:
                 # Format: "`value`:"
@@ -228,16 +245,13 @@ class CalloutDetector:
                 if value_text:
                     all_lines.append(f"{value_text}:")
 
-                # Add additional value lines if multi-line
+                # Add additional value lines if multi-line (includes conditionals and blank lines)
                 for line in value_lines[1:]:
                     all_lines.append(line)
 
-            # Add description lines
+            # Add description lines (already includes conditionals and blank lines)
             all_lines.extend(description_lines)
 
-            # Add conditionals as separate lines (they'll be preserved in output)
-            all_lines.extend(conditionals)
-
             # Check if marked as optional
             is_optional = False
             if all_lines and (all_lines[0].lower().startswith('optional.') or
@@ -252,6 +266,10 @@ class CalloutDetector:
 
     def _extract_from_list(self, lines: List[str], start_line: int) -> Tuple[Dict[int, Callout], int]:
         """Extract callout explanations from list format (<1> text)."""
+        # Clear table data since list format doesn't have tables
+        self.last_table = None
+        self.last_table_title = ""
+
         explanations = {}
         i = start_line + 1  # Start after the closing delimiter
 
@@ -306,17 +324,33 @@ class CalloutDetector:
             cleaned.append(self.CALLOUT_WITH_COMMENT.sub('', line).rstrip())
         return cleaned
 
-    def validate_callouts(self, callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> Tuple[bool, set, set]:
+    def validate_callouts(self, callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> Tuple[bool, List[int], List[int]]:
         """
         Validate that callout numbers in code match explanation numbers.
-        Returns tuple of (is_valid, code_nums, explanation_nums).
+        Returns tuple of (is_valid, code_nums_list, explanation_nums_list).
+
+        Returns:
+            - is_valid: True if unique callout numbers match
+            - code_nums_list: List of callout numbers from code (unique, sorted)
+            - explanation_nums_list: List of callout numbers from explanations
+              (preserves duplicates if from table, sorted)
         """
-        # Extract all callout numbers from groups
-        code_nums = set()
+        # Extract unique callout numbers from code groups
+        code_nums_set = set()
         for group in callout_groups:
-            code_nums.update(group.callout_numbers)
+            code_nums_set.update(group.callout_numbers)
+
+        # Get explanation numbers, preserving duplicates if from a table
+        if self.last_table:
+            # Use table parser to get raw callout numbers (with duplicates)
+            explanation_nums_list = self.table_parser.get_table_callout_numbers(self.last_table)
+        else:
+            # List format: dict keys are already unique
+            explanation_nums_list = list(explanations.keys())
+
+        explanation_nums_set = set(explanation_nums_list)
 
-        explanation_nums = set(explanations.keys())
+        # Validation compares unique numbers only
+        is_valid = code_nums_set == explanation_nums_set
 
-        is_valid = code_nums == explanation_nums
-        return is_valid, code_nums, explanation_nums
+        return is_valid, sorted(code_nums_set), sorted(explanation_nums_list)