rolfedh-doc-utils 0.1.22__tar.gz → 0.1.24__tar.gz

{rolfedh_doc_utils-0.1.22/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.24}/PKG-INFO

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

{rolfedh_doc_utils-0.1.22 → rolfedh_doc_utils-0.1.24}/convert_callouts_to_deflist.py

@@ -34,10 +34,17 @@ def print_colored(message: str, color: str = Colors.NC) -> None:
 class Callout:
     """Represents a callout with its number and explanation text."""
     number: int
-    text: str
+    lines: List[str]  # List of lines to preserve formatting
     is_optional: bool = False
 
 
+@dataclass
+class CalloutGroup:
+    """Represents one or more callouts that share the same code line."""
+    code_line: str  # The actual code line (without callouts)
+    callout_numbers: List[int]  # List of callout numbers on this line
+
+
 @dataclass
 class CodeBlock:
     """Represents a code block with its content and metadata."""
@@ -51,11 +58,12 @@ class CodeBlock:
 class CalloutConverter:
     """Converts callout-style documentation to definition list format."""
 
-    # Pattern for code block start: [source,language] or [source]
-    CODE_BLOCK_START = re.compile(r'^\[source(?:,\s*(\w+))?\]')
+    # Pattern for code block start: [source,language] or [source] with optional attributes
+    # Matches: [source], [source,java], [source,java,subs="..."], [source,java,options="..."], etc.
+    CODE_BLOCK_START = re.compile(r'^\[source(?:,\s*(\w+))?(?:[,\s]+[^\]]+)?\]')
 
-    # Pattern for callout number at end of line in code block
-    CALLOUT_IN_CODE = re.compile(r'<(\d+)>\s*$')
+    # Pattern for callout number in code block (can appear multiple times per line)
+    CALLOUT_IN_CODE = re.compile(r'<(\d+)>')
 
     # Pattern for callout explanation line: <1> Explanation text
     CALLOUT_EXPLANATION = re.compile(r'^<(\d+)>\s+(.+)$')
@@ -64,9 +72,10 @@ class CalloutConverter:
     # Excludes heredoc syntax (<<) and comparison operators
     USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
 
-    def __init__(self, dry_run: bool = False, verbose: bool = False):
+    def __init__(self, dry_run: bool = False, verbose: bool = False, output_format: str = 'deflist'):
         self.dry_run = dry_run
         self.verbose = verbose
+        self.output_format = output_format  # 'deflist' or 'bullets'
         self.changes_made = 0
         self.warnings = []  # Collect warnings for summary
 
@@ -81,6 +90,7 @@ class CalloutConverter:
         i = 0
 
         while i < len(lines):
+            # Check for [source] prefix first
             match = self.CODE_BLOCK_START.match(lines[i])
             if match:
                 language = match.group(1)
@@ -106,44 +116,71 @@ class CalloutConverter:
                             ))
                             break
                         i += 1
+            # Check for plain delimited blocks without [source] prefix
+            elif lines[i].strip() in ['----', '....']:
+                delimiter = lines[i].strip()
+                start = i
+                i += 1
+                content_start = i
+
+                # Find the closing delimiter
+                while i < len(lines):
+                    if lines[i].strip() == delimiter:
+                        content = lines[content_start:i]
+                        # Only add if block contains callouts
+                        if any(self.CALLOUT_IN_CODE.search(line) for line in content):
+                            blocks.append(CodeBlock(
+                                start_line=start,
+                                end_line=i,
+                                delimiter=delimiter,
+                                content=content,
+                                language=None
+                            ))
+                        break
+                    i += 1
             i += 1
 
         return blocks
 
-    def extract_callouts_from_code(self, content: List[str]) -> Dict[int, Optional[str]]:
+    def extract_callouts_from_code(self, content: List[str]) -> List[CalloutGroup]:
         """
         Extract callout numbers from code block content.
-        Returns dict mapping callout number to either:
-        - The user-replaceable value (if angle brackets found), or
-        - The actual code line (for callouts explaining code behavior)
+        Returns list of CalloutGroups, where each group contains:
+        - The code line (with user-replaceable value if found, or full line)
+        - List of callout numbers on that line
 
-        For each callout, attempts to extract the most relevant user-replaceable value
-        by looking for angle-bracket enclosed values on the same line.
+        Multiple callouts on the same line are grouped together to be merged
+        in the definition list.
         """
-        callouts = {}
+        groups = []
 
         for line in content:
-            # Look for callout number at end of line
-            callout_match = self.CALLOUT_IN_CODE.search(line)
-            if callout_match:
-                callout_num = int(callout_match.group(1))
-
-                # Extract the user-replaceable value (content in angle brackets)
-                # Remove the callout number first
-                line_without_callout = self.CALLOUT_IN_CODE.sub('', line).strip()
+            # 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()
 
                 # Find all angle-bracket enclosed values
-                user_values = self.USER_VALUE_PATTERN.findall(line_without_callout)
+                user_values = self.USER_VALUE_PATTERN.findall(line_without_callouts)
 
+                # Determine what to use as the code line term
                 if user_values:
                     # Use the rightmost (closest to the callout) user value
-                    callouts[callout_num] = user_values[-1]
+                    code_line = user_values[-1]
                 else:
-                    # No angle-bracket value found - store the actual code line
-                    # This will be used as the term in the definition list
-                    callouts[callout_num] = line_without_callout
+                    # No angle-bracket value found - use the actual code line
+                    code_line = line_without_callouts
+
+                # Collect all callout numbers on this line
+                callout_nums = [int(m.group(1)) for m in callout_matches]
 
-        return callouts
+                groups.append(CalloutGroup(
+                    code_line=code_line,
+                    callout_numbers=callout_nums
+                ))
+
+        return groups
 
     def extract_callout_explanations(self, lines: List[str], start_line: int) -> Tuple[Dict[int, Callout], int]:
         """
@@ -153,8 +190,8 @@ class CalloutConverter:
         explanations = {}
         i = start_line + 1  # Start after the closing delimiter
 
-        # Skip blank lines
-        while i < len(lines) and not lines[i].strip():
+        # Skip blank lines and continuation markers (+)
+        while i < len(lines) and (not lines[i].strip() or lines[i].strip() == '+'):
             i += 1
 
         # Collect consecutive callout explanation lines
@@ -162,31 +199,48 @@ class CalloutConverter:
             match = self.CALLOUT_EXPLANATION.match(lines[i])
             if match:
                 num = int(match.group(1))
-                text = match.group(2).strip()
+                first_line = match.group(2).strip()
+                explanation_lines = [first_line]
+                i += 1
 
-                # Check if marked as optional
+                # Collect continuation lines (lines that don't start with a new callout)
+                # Continue until we hit a blank line, a new callout, or certain patterns
+                while i < len(lines):
+                    line = lines[i]
+                    # Stop if we hit a blank line, new callout, or list start marker
+                    if not line.strip() or self.CALLOUT_EXPLANATION.match(line) or line.startswith('[start='):
+                        break
+                    # Add continuation line preserving original formatting
+                    explanation_lines.append(line)
+                    i += 1
+
+                # Check if marked as optional (only in first line)
                 is_optional = False
-                if text.lower().startswith('optional.') or text.lower().startswith('optional:'):
+                if first_line.lower().startswith('optional.') or first_line.lower().startswith('optional:'):
                     is_optional = True
-                    text = text[9:].strip()  # Remove "Optional." or "Optional:"
-                elif '(Optional)' in text or '(optional)' in text:
+                    # Remove "Optional." or "Optional:" from first line
+                    explanation_lines[0] = first_line[9:].strip()
+                elif '(Optional)' in first_line or '(optional)' in first_line:
                     is_optional = True
-                    text = re.sub(r'\s*\(optional\)\s*', ' ', text, flags=re.IGNORECASE).strip()
+                    explanation_lines[0] = re.sub(r'\s*\(optional\)\s*', ' ', first_line, flags=re.IGNORECASE).strip()
 
-                explanations[num] = Callout(num, text, is_optional)
-                i += 1
+                explanations[num] = Callout(num, explanation_lines, is_optional)
             else:
                 break
 
         return explanations, i - 1
 
-    def validate_callouts(self, code_callouts: Dict[int, str], explanations: Dict[int, Callout],
+    def validate_callouts(self, callout_groups: List[CalloutGroup], explanations: Dict[int, Callout],
                          input_file: Path = None, block_start: int = None, block_end: int = None) -> bool:
         """
         Validate that callout numbers in code match explanation numbers.
         Returns True if valid, False otherwise.
         """
-        code_nums = set(code_callouts.keys())
+        # Extract all callout numbers from groups
+        code_nums = set()
+        for group in callout_groups:
+            code_nums.update(group.callout_numbers)
+
         explanation_nums = set(explanations.keys())
 
         if code_nums != explanation_nums:
@@ -208,31 +262,35 @@ class CalloutConverter:
         return True
 
     def remove_callouts_from_code(self, content: List[str]) -> List[str]:
-        """Remove callout numbers from code block content."""
+        """Remove callout numbers from code block content (handles multiple callouts per line)."""
         cleaned = []
         for line in content:
-            cleaned.append(self.CALLOUT_IN_CODE.sub('', line))
+            # Remove all callout numbers and trailing whitespace
+            cleaned.append(self.CALLOUT_IN_CODE.sub('', line).rstrip())
         return cleaned
 
-    def create_definition_list(self, code_callouts: Dict[int, str], explanations: Dict[int, Callout]) -> List[str]:
+    def create_definition_list(self, callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> List[str]:
         """
-        Create definition list from callouts and explanations.
+        Create definition list from callout groups and explanations.
 
         For callouts with user-replaceable values in angle brackets, uses those.
         For callouts without values, uses the actual code line as the term.
+
+        When multiple callouts share the same code line (same group), their
+        explanations are merged using AsciiDoc list continuation (+).
         """
-        lines = ['\nwhere:\n']
+        lines = ['\nwhere:']
 
-        # Sort by callout number
-        for num in sorted(code_callouts.keys()):
-            value = code_callouts[num]
-            explanation = explanations[num]
+        # Process each group (which may contain one or more callouts)
+        for group in callout_groups:
+            code_line = group.code_line
+            callout_nums = group.callout_numbers
 
             # Check if this is a user-replaceable value (contains angle brackets but not heredoc)
             # User values are single words/phrases in angle brackets like <my-value>
-            user_values = self.USER_VALUE_PATTERN.findall(value)
+            user_values = self.USER_VALUE_PATTERN.findall(code_line)
 
-            if user_values and len(user_values) == 1 and len(value) < 100:
+            if user_values and len(user_values) == 1 and len(code_line) < 100:
                 # This looks like a user-replaceable value placeholder
                 # Format the value (ensure it has angle brackets)
                 user_value = user_values[0]
@@ -243,15 +301,97 @@ class CalloutConverter:
                 term = f'`{user_value}`'
             else:
                 # This is a code line - use it as-is in backticks
-                term = f'`{value}`'
+                term = f'`{code_line}`'
+
+            # Add blank line before each term
+            lines.append('')
+            lines.append(f'{term}::')
 
-            # Prepend "Optional. " to the explanation text if marked as optional
-            explanation_text = explanation.text
-            if explanation.is_optional:
-                explanation_text = f'Optional. {explanation_text}'
+            # Add explanations for all callouts in this group
+            for idx, callout_num in enumerate(callout_nums):
+                explanation = explanations[callout_num]
 
-            lines.append(f'\n{term}::')
-            lines.append(f'{explanation_text}\n')
+                # If this is not the first explanation in the group, add continuation marker
+                if idx > 0:
+                    lines.append('+')
+
+                # Add explanation lines, prepending "Optional. " to first line if needed
+                for line_idx, line in enumerate(explanation.lines):
+                    if line_idx == 0 and explanation.is_optional:
+                        lines.append(f'Optional. {line}')
+                    else:
+                        lines.append(line)
+
+        return lines
+
+    def create_bulleted_list(self, callout_groups: List[CalloutGroup], explanations: Dict[int, Callout]) -> List[str]:
+        """
+        Create bulleted list from callout groups and explanations.
+
+        Follows Red Hat style guide format:
+        - Each bullet starts with `*` followed by backticked code element
+        - Colon separates element from explanation
+        - Blank line between each bullet point
+
+        For callouts with user-replaceable values in angle brackets, uses those.
+        For callouts without values, uses the actual code line as the term.
+
+        When multiple callouts share the same code line (same group), their
+        explanations are merged with line breaks.
+        """
+        lines = ['']  # Start with blank line before list
+
+        # Process each group (which may contain one or more callouts)
+        for group in callout_groups:
+            code_line = group.code_line
+            callout_nums = group.callout_numbers
+
+            # Check if this is a user-replaceable value (contains angle brackets but not heredoc)
+            # User values are single words/phrases in angle brackets like <my-value>
+            user_values = self.USER_VALUE_PATTERN.findall(code_line)
+
+            if user_values and len(user_values) == 1 and len(code_line) < 100:
+                # This looks like a user-replaceable value placeholder
+                # Format the value (ensure it has angle brackets)
+                user_value = user_values[0]
+                if not user_value.startswith('<'):
+                    user_value = f'<{user_value}>'
+                if not user_value.endswith('>'):
+                    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}`'
+
+            # Collect all explanations for this group
+            all_explanation_lines = []
+            for idx, callout_num in enumerate(callout_nums):
+                explanation = explanations[callout_num]
+
+                # Add explanation lines, prepending "Optional. " to first line if needed
+                for line_idx, line in enumerate(explanation.lines):
+                    if line_idx == 0 and explanation.is_optional:
+                        all_explanation_lines.append(f'Optional. {line}')
+                    else:
+                        all_explanation_lines.append(line)
+
+                # If there are more callouts in this group, add a line break
+                if idx < len(callout_nums) - 1:
+                    all_explanation_lines.append('')
+
+            # Format as bullet point: * `term`: explanation
+            # First line uses the bullet marker
+            lines.append(f'*   {term}: {all_explanation_lines[0]}')
+
+            # Continuation lines (if any) are indented to align with first line
+            for continuation_line in all_explanation_lines[1:]:
+                if continuation_line:  # Skip empty lines for now
+                    lines.append(f'    {continuation_line}')
+                else:
+                    lines.append('')
+
+            # Add blank line after each bullet point
+            lines.append('')
 
         return lines
 
@@ -282,14 +422,19 @@ class CalloutConverter:
         conversions = 0
 
         for block in reversed(blocks):
-            # Extract callouts from code
-            code_callouts = self.extract_callouts_from_code(block.content)
+            # Extract callouts from code (returns list of CalloutGroups)
+            callout_groups = self.extract_callouts_from_code(block.content)
 
-            if not code_callouts:
+            if not callout_groups:
                 self.log(f"No callouts in block at line {block.start_line + 1}")
                 continue
 
-            self.log(f"Block at line {block.start_line + 1} has callouts: {list(code_callouts.keys())}")
+            # Extract all callout numbers for logging
+            all_callout_nums = []
+            for group in callout_groups:
+                all_callout_nums.extend(group.callout_numbers)
+
+            self.log(f"Block at line {block.start_line + 1} has callouts: {all_callout_nums}")
 
             # Extract explanations
             explanations, explanation_end = self.extract_callout_explanations(new_lines, block.end_line)
@@ -299,7 +444,7 @@ class CalloutConverter:
                 continue
 
             # Validate callouts match
-            if not self.validate_callouts(code_callouts, explanations, input_file, block.start_line, block.end_line):
+            if not self.validate_callouts(callout_groups, explanations, input_file, block.start_line, block.end_line):
                 continue
 
             self.log(f"Converting block at line {block.start_line + 1}")
@@ -307,12 +452,20 @@ class CalloutConverter:
             # Remove callouts from code
             cleaned_content = self.remove_callouts_from_code(block.content)
 
-            # Create definition list
-            def_list = self.create_definition_list(code_callouts, explanations)
+            # Create output list (definition list or bulleted list based on format option)
+            if self.output_format == 'bullets':
+                output_list = self.create_bulleted_list(callout_groups, explanations)
+            else:  # default to 'deflist'
+                output_list = self.create_definition_list(callout_groups, explanations)
 
             # Replace in document
             # 1. Update code block content
-            content_start = block.start_line + 2  # After [source] and ----
+            # Check if block has [source] prefix by checking if start_line contains [source]
+            has_source_prefix = self.CODE_BLOCK_START.match(new_lines[block.start_line])
+            if has_source_prefix:
+                content_start = block.start_line + 2  # After [source] and ----
+            else:
+                content_start = block.start_line + 1  # After ---- only
             content_end = block.end_line
 
             # 2. Remove old callout explanations
@@ -325,7 +478,7 @@ class CalloutConverter:
                 new_lines[:content_start] +
                 cleaned_content +
                 [new_lines[content_end]] +  # Keep closing delimiter
-                def_list +
+                output_list +
                 new_lines[explanation_end + 1:]
             )
 
@@ -478,6 +631,12 @@ Example transformation:
         action='store_true',
         help='Enable verbose output'
     )
+    parser.add_argument(
+        '-f', '--format',
+        choices=['deflist', 'bullets'],
+        default='deflist',
+        help='Output format: "deflist" for definition list with "where:" (default), "bullets" for bulleted list'
+    )
     parser.add_argument(
         '--exclude-dir',
         action='append',
@@ -535,7 +694,7 @@ Example transformation:
     print(f"Found {len(adoc_files)} AsciiDoc file(s) to process")
 
     # Create converter
-    converter = CalloutConverter(dry_run=args.dry_run, verbose=args.verbose)
+    converter = CalloutConverter(dry_run=args.dry_run, verbose=args.verbose, output_format=args.format)
 
     # Process each file
     files_processed = 0

{rolfedh_doc_utils-0.1.22 → rolfedh_doc_utils-0.1.24}/pyproject.toml

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

{rolfedh_doc_utils-0.1.22 → rolfedh_doc_utils-0.1.24/rolfedh_doc_utils.egg-info}/PKG-INFO

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