rolfedh-doc-utils 0.1.26__py3-none-any.whl → 0.1.28__py3-none-any.whl

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 = []

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('')

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]:

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

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.dist-info → rolfedh_doc_utils-0.1.28.dist-info}/METADATA

@@ -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.dist-info → rolfedh_doc_utils-0.1.28.dist-info}/RECORD

@@ -2,7 +2,7 @@ archive_unused_files.py,sha256=OJZrkqn70hiOXED218jMYPFNFWnsDpjsCYOmBRxYnHU,2274
 archive_unused_images.py,sha256=fZeyEZtTd72Gbd3YBXTy5xoshAAM9qb4qFPMjhHL1Fg,1864
 check_scannability.py,sha256=O6ROr-e624jVPvPpASpsWo0gTfuCFpA2mTSX61BjAEI,5478
 convert_callouts_interactive.py,sha256=hoDKff3jqyJiGZ3IqjcWF7AXM4XUQE-vVg2NpJYECs4,21066
-convert_callouts_to_deflist.py,sha256=WRpHmD3DWs7G7qEcL6c9WLYpX4uaPzlMKrWXnPlHQ_s,17720
+convert_callouts_to_deflist.py,sha256=MfNbbTzaODFIK6jdPdCoMCe27KqMjJFjdoIiGazm978,17852
 doc_utils_cli.py,sha256=dsMYrkAriYdZUF0_cSPh5DAPrJMPiecuY26xN-p0UJ0,4911
 extract_link_attributes.py,sha256=wR2SmR2la-jR6DzDbas2PoNONgRZ4dZ6aqwzkwEv8Gs,3516
 find_unused_attributes.py,sha256=77CxFdm72wj6SO81w-auMdDjnvF83jWy_qaM7DsAtBw,4263
@@ -10,11 +10,11 @@ format_asciidoc_spacing.py,sha256=nmWpw2dgwhd81LXyznq0rT8w6Z7cNRyGtPJGRyKFRdc,42
 replace_link_attributes.py,sha256=Cpc4E-j9j-4_y0LOstAKYOPl02Ln_2bGNIeqp3ZVCdA,7624
 validate_links.py,sha256=lWuK8sgfiFdfcUdSVAt_5U9JHVde_oa6peSUlBQtsac,6145
 callout_lib/__init__.py,sha256=8B82N_z4D1LaZVYgd5jZR53QAabtgPzADOyGlnvihj0,665
-callout_lib/converter_bullets.py,sha256=8P92QZ0PylrKRE7V-D3TVZCDH0ct3GRIonc7W5AK5uU,3898
+callout_lib/converter_bullets.py,sha256=ZYQIddaouEouPkrDRGIt8f35a1rO5M92Ry5Fi5ZL_2g,3926
 callout_lib/converter_comments.py,sha256=do0dH8uOyNFpn5CDEzR0jYYCMIPP3oPFM8cEB-Fp22c,9767
-callout_lib/converter_deflist.py,sha256=mQ17Y8gJLv0MzzJscpUL7ujuDRyEVcrb9lcPdUNkIX4,3117
-callout_lib/detector.py,sha256=qMFb8MZGYWhEXqV-Bn9BW0qXlYgJcVwKyPI-50oYl5U,10937
-callout_lib/table_parser.py,sha256=0sngxSXdVxc9vs6umeV6hgOIP2ETC7I_RbrEuSntB6k,15505
+callout_lib/converter_deflist.py,sha256=ghXX04L1QRNfsSKGXZsL839IoC-bd8PiNdrSSw_clwI,3145
+callout_lib/detector.py,sha256=TYYcQjx77-aZe8A4MK5w_CTojGrOUb8qYjiwyXeJqCk,13699
+callout_lib/table_parser.py,sha256=_e-viN7ijrL2gFdjem5hYirJv_8HH9f67yWUDkiQflQ,21672
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
@@ -29,9 +29,9 @@ doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,14
 doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
 doc_utils/version.py,sha256=5Uc0sAUOkXA6R_PvDGjw2MBYptEKdav5XmeRqukMTo0,203
 doc_utils/version_check.py,sha256=eHJnZmBTbdhhY2fJQW9KnnyD0rWEvCZpMg6oSr0fOmI,7090
-rolfedh_doc_utils-0.1.26.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.26.dist-info/METADATA,sha256=ni6hzbVbd9CcWp73tFf688p7g5xaWXqsASphw0Bb4kA,8325
-rolfedh_doc_utils-0.1.26.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.26.dist-info/entry_points.txt,sha256=vL_LlLKOiurRzchrq8iRUQG19Xi9lSAFVZGjO-xyErk,577
-rolfedh_doc_utils-0.1.26.dist-info/top_level.txt,sha256=J4xtr3zoyCip27b3GnticFVZoyz5HHtgGqHQ-SZONCA,265
-rolfedh_doc_utils-0.1.26.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.28.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.28.dist-info/METADATA,sha256=Wm-meTVYlYyDhxPGawv2LOlhPNuNfvnwkIFHRyqqCkw,8325
+rolfedh_doc_utils-0.1.28.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.28.dist-info/entry_points.txt,sha256=vL_LlLKOiurRzchrq8iRUQG19Xi9lSAFVZGjO-xyErk,577
+rolfedh_doc_utils-0.1.28.dist-info/top_level.txt,sha256=J4xtr3zoyCip27b3GnticFVZoyz5HHtgGqHQ-SZONCA,265
+rolfedh_doc_utils-0.1.28.dist-info/RECORD,,