rolfedh-doc-utils 0.1.26__tar.gz → 0.1.28__tar.gz

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.26
+Version: 0.1.28
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/callout_lib/converter_bullets.py

@@ -59,8 +59,8 @@ class BulletListConverter:
                     user_value = f'{user_value}>'
                 term = f'`{user_value}`'
             else:
-                # This is a code line - use it as-is in backticks
-                term = f'`{code_line}`'
+                # This is a code line - strip whitespace before wrapping in backticks
+                term = f'`{code_line.strip()}`'
 
             # Collect all explanations for this group
             all_explanation_lines = []

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/callout_lib/converter_deflist.py

@@ -54,8 +54,8 @@ class DefListConverter:
                     user_value = f'{user_value}>'
                 term = f'`{user_value}`'
             else:
-                # This is a code line - use it as-is in backticks
-                term = f'`{code_line}`'
+                # This is a code line - strip whitespace before wrapping in backticks
+                term = f'`{code_line.strip()}`'
 
             # Add blank line before each term
             lines.append('')

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/callout_lib/detector.py

@@ -45,6 +45,11 @@ class CalloutDetector:
     # Pattern for callout number in code block (can appear multiple times per line)
     CALLOUT_IN_CODE = re.compile(r'<(\d+)>')
 
+    # Pattern for callout with optional preceding comment syntax
+    # Matches common comment styles: //, #, --, ;, followed by optional whitespace and <number>
+    # The comment syntax must be preceded by whitespace to avoid matching code operators
+    CALLOUT_WITH_COMMENT = re.compile(r'\s*(?://|#|--|;)\s*<\d+>|\s*<\d+>')
+
     # Pattern for callout explanation line: <1> Explanation text
     CALLOUT_EXPLANATION = re.compile(r'^<(\d+)>\s+(.+)$')
 
@@ -130,8 +135,9 @@ class CalloutDetector:
             # Look for all callout numbers on this line
             callout_matches = list(self.CALLOUT_IN_CODE.finditer(line))
             if callout_matches:
-                # Remove all callouts from the line to get the actual code
-                line_without_callouts = self.CALLOUT_IN_CODE.sub('', line).strip()
+                # Remove callouts AND preceding comment syntax from the line
+                # Use CALLOUT_WITH_COMMENT to remove both comment syntax and callout
+                line_without_callouts = self.CALLOUT_WITH_COMMENT.sub('', line).rstrip()
 
                 # Find all angle-bracket enclosed values
                 user_values = self.USER_VALUE_PATTERN.findall(line_without_callouts)
@@ -157,13 +163,18 @@ class CalloutDetector:
     def extract_callout_explanations(self, lines: List[str], start_line: int) -> Tuple[Dict[int, Callout], int]:
         """
         Extract callout explanations following a code block.
-        Supports both list-format (<1> text) and table-format explanations.
+        Supports list-format (<1> text), 2-column table, and 3-column table formats.
         Returns dict of callouts and the line number where explanations end.
         """
         # First, try to find a table-format callout explanation
         table = self.table_parser.find_callout_table_after_code_block(lines, start_line)
         if table:
-            return self._extract_from_table(table)
+            # Check if it's a 3-column table (Item | Value | Description)
+            if self.table_parser.is_3column_callout_table(table):
+                return self._extract_from_3column_table(table)
+            # Check if it's a 2-column table (<callout> | explanation)
+            elif self.table_parser.is_callout_table(table):
+                return self._extract_from_table(table)
 
         # Fall back to list-format extraction
         return self._extract_from_list(lines, start_line)
@@ -196,6 +207,49 @@ class CalloutDetector:
 
         return explanations, table.end_line
 
+    def _extract_from_3column_table(self, table) -> Tuple[Dict[int, Callout], int]:
+        """
+        Extract callout explanations from a 3-column table format.
+        Format: Item (number) | Value | Description
+        """
+        explanations = {}
+        table_data = self.table_parser.extract_3column_callout_explanations(table)
+
+        for callout_num, (value_lines, description_lines, conditionals) in table_data.items():
+            # Combine value and description into explanation lines
+            # Strategy: Include value as context, then description
+            all_lines = []
+
+            # Add value lines with context
+            if value_lines:
+                # Format: "`value`:"
+                value_text = value_lines[0] if value_lines else ""
+                # If value is code-like (contains backticks or special chars), keep it formatted
+                if value_text:
+                    all_lines.append(f"{value_text}:")
+
+                # Add additional value lines if multi-line
+                for line in value_lines[1:]:
+                    all_lines.append(line)
+
+            # Add description 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
+                             all_lines[0].lower().startswith('optional:') or
+                             'optional' in all_lines[0].lower()[:50]):  # Check first 50 chars
+                is_optional = True
+                # Don't remove "optional" text - it's part of the description
+
+            explanations[callout_num] = Callout(callout_num, all_lines, is_optional)
+
+        return explanations, table.end_line
+
     def _extract_from_list(self, lines: List[str], start_line: int) -> Tuple[Dict[int, Callout], int]:
         """Extract callout explanations from list format (<1> text)."""
         explanations = {}
@@ -242,11 +296,14 @@ class CalloutDetector:
         return explanations, i - 1
 
     def remove_callouts_from_code(self, content: List[str]) -> List[str]:
-        """Remove callout numbers from code block content (handles multiple callouts per line)."""
+        """
+        Remove callout numbers and preceding comment syntax from code block content.
+        Handles multiple callouts per line and various comment styles (//,  #, --, ;).
+        """
         cleaned = []
         for line in content:
-            # Remove all callout numbers and trailing whitespace
-            cleaned.append(self.CALLOUT_IN_CODE.sub('', line).rstrip())
+            # Remove all callout numbers with their preceding comment syntax
+            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]:

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/callout_lib/table_parser.py

@@ -188,9 +188,34 @@ class TableParser:
 
                 # Extract cell content from this line (text after |)
                 cell_content = line[1:].strip()  # Remove leading |
-                if cell_content:
-                    current_cell_lines.append(cell_content)
-                # If empty, just start a new cell with no content yet
+
+                # Check if there are multiple cells on the same line (e.g., |Cell1 |Cell2 |Cell3)
+                if '|' in cell_content:
+                    # Split by | to get multiple cells
+                    parts = cell_content.split('|')
+                    for part in parts:
+                        part = part.strip()
+                        if part:  # Skip empty parts
+                            current_row_cells.append(TableCell(
+                                content=[part],
+                                conditionals=[]
+                            ))
+
+                    # Multi-cell line completes a row - finalize it
+                    if current_row_cells:
+                        rows.append(TableRow(
+                            cells=current_row_cells.copy(),
+                            conditionals_before=conditionals_before_row.copy(),
+                            conditionals_after=conditionals_after_row.copy()
+                        ))
+                        current_row_cells = []
+                        conditionals_before_row = []
+                        conditionals_after_row = []
+                else:
+                    # Single cell on this line
+                    if cell_content:
+                        current_cell_lines.append(cell_content)
+                    # If empty, just start a new cell with no content yet
 
                 i += 1
                 continue
@@ -229,6 +254,65 @@ class TableParser:
 
         return True
 
+    def _has_header_row(self, table: AsciiDocTable) -> bool:
+        """
+        Check if table has a header row.
+        Common header patterns: "Item", "Value", "Description", "Column", etc.
+        """
+        if not table.rows:
+            return False
+
+        first_row = table.rows[0]
+        if not first_row.cells:
+            return False
+
+        # Collect text from all cells in first row
+        header_text = ' '.join(
+            cell.content[0] if cell.content else ''
+            for cell in first_row.cells
+        ).lower()
+
+        # Check for common header keywords
+        header_keywords = ['item', 'description', 'value', 'column', 'parameter', 'field', 'name']
+        return any(keyword in header_text for keyword in header_keywords)
+
+    def is_3column_callout_table(self, table: AsciiDocTable) -> bool:
+        """
+        Determine if a table is a 3-column callout explanation table.
+        Format: Item (number) | Value | Description
+
+        This format is used in some documentation (e.g., Debezium) where:
+        - Column 1: Item number (1, 2, 3...) corresponding to callout numbers
+        - Column 2: The value/code being explained
+        - Column 3: Description/explanation text
+        """
+        if not table.rows:
+            return False
+
+        # Determine if there's a header row
+        has_header = self._has_header_row(table)
+        data_rows = table.rows[1:] if has_header else table.rows
+
+        if not data_rows:
+            return False
+
+        # Check if all data rows have exactly 3 cells
+        if not all(len(row.cells) == 3 for row in data_rows):
+            return False
+
+        # Check if first cell of each data row contains a plain number (1, 2, 3...)
+        for row in data_rows:
+            first_cell = row.cells[0]
+            if not first_cell.content:
+                return False
+
+            # First line of first cell should be a number
+            first_line = first_cell.content[0].strip()
+            if not first_line.isdigit():
+                return False
+
+        return True
+
     def extract_callout_explanations_from_table(self, table: AsciiDocTable) -> Dict[int, Tuple[List[str], List[str]]]:
         """
         Extract callout explanations from a table.
@@ -276,6 +360,77 @@ class TableParser:
 
         return explanations
 
+    def extract_3column_callout_explanations(self, table: AsciiDocTable) -> Dict[int, Tuple[List[str], List[str], List[str]]]:
+        """
+        Extract callout explanations from a 3-column table.
+        Returns dict mapping callout number to tuple of (value_lines, description_lines, conditionals).
+
+        Format: Item | Value | Description
+        - Item: Number (1, 2, 3...) corresponding to callout number
+        - Value: The code/value being explained
+        - Description: Explanation text
+
+        The conditionals list includes any ifdef/ifndef/endif statements that should
+        be preserved when converting the table to other formats.
+        """
+        explanations = {}
+
+        # Determine if there's a header row and skip it
+        has_header = self._has_header_row(table)
+        data_rows = table.rows[1:] if has_header else table.rows
+
+        for row in data_rows:
+            if len(row.cells) != 3:
+                continue
+
+            item_cell = row.cells[0]
+            value_cell = row.cells[1]
+            desc_cell = row.cells[2]
+
+            # Extract item number (maps to callout number)
+            if not item_cell.content:
+                continue
+
+            item_num_str = item_cell.content[0].strip()
+            if not item_num_str.isdigit():
+                continue
+
+            callout_num = int(item_num_str)
+
+            # Collect value lines (column 2)
+            value_lines = []
+            for line in value_cell.content:
+                # Skip conditional directives in value (preserve them separately)
+                if not (self.IFDEF_PATTERN.match(line) or self.ENDIF_PATTERN.match(line)):
+                    value_lines.append(line)
+
+            # Collect description lines (column 3)
+            description_lines = []
+            for line in desc_cell.content:
+                # Skip conditional directives in description (preserve them separately)
+                if not (self.IFDEF_PATTERN.match(line) or self.ENDIF_PATTERN.match(line)):
+                    description_lines.append(line)
+
+            # Collect all conditionals for this row
+            all_conditionals = []
+            all_conditionals.extend(row.conditionals_before)
+
+            # Extract conditionals from value cell
+            for line in value_cell.content:
+                if self.IFDEF_PATTERN.match(line) or self.ENDIF_PATTERN.match(line):
+                    all_conditionals.append(line)
+
+            # Extract conditionals from description cell
+            for line in desc_cell.content:
+                if self.IFDEF_PATTERN.match(line) or self.ENDIF_PATTERN.match(line):
+                    all_conditionals.append(line)
+
+            all_conditionals.extend(row.conditionals_after)
+
+            explanations[callout_num] = (value_lines, description_lines, all_conditionals)
+
+        return explanations
+
     def find_callout_table_after_code_block(self, lines: List[str], code_block_end: int) -> Optional[AsciiDocTable]:
         """
         Find a callout explanation table that appears after a code block.
@@ -316,7 +471,7 @@ class TableParser:
                     start_line = j - 1
 
                 table = self._parse_table(lines, start_line, j)
-                if table and self.is_callout_table(table):
+                if table and (self.is_callout_table(table) or self.is_3column_callout_table(table)):
                     return table
 
                 # If we found a table but it's not a callout table, stop searching

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/convert_callouts_to_deflist.py

@@ -166,14 +166,15 @@ class CalloutConverter:
                 content_start = block.start_line + 1  # After ---- only
             content_end = block.end_line
 
-            # For comments format (without fallback), we keep the explanations section
-            # For deflist/bullets format, we remove old explanations and add new list
+            # For comments format (without fallback), remove explanations but don't add new list
+            # For deflist/bullets format, remove old explanations and add new list
             if self.output_format == 'comments' and not use_deflist_fallback:
-                # Keep everything as-is, just replace code content
+                # Remove old callout explanations (list or table format)
                 new_section = (
                     new_lines[:content_start] +
                     converted_content +
-                    new_lines[content_end:]
+                    [new_lines[content_end]] +  # Keep closing delimiter
+                    new_lines[explanation_end + 1:]  # Skip explanations/table, keep rest
                 )
             else:
                 # Remove old callout explanations and add new list

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.26"
+version = "0.1.28"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"

{rolfedh_doc_utils-0.1.26 → rolfedh_doc_utils-0.1.28}/rolfedh_doc_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.26
+Version: 0.1.28
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License