rolfedh-doc-utils 0.1.4__py3-none-any.whl → 0.1.41__py3-none-any.whl

archive_unused_files.py

@@ -1,35 +1,48 @@
 """
 Archive Unused AsciiDoc Files
 
-Scans './modules' and './assemblies' for AsciiDoc files not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them.
+Automatically discovers and scans 'modules' and 'assemblies' directories for AsciiDoc files 
+not referenced by any other AsciiDoc file in the project. Optionally archives and deletes them.
 
 For full documentation and usage examples, see archive_unused_files.md in this directory.
 """
 
 import argparse
 from doc_utils.unused_adoc import find_unused_adoc
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
+from doc_utils.version import __version__
 
+from doc_utils.spinner import Spinner
 def main():
-    parser = argparse.ArgumentParser(description='Archive unused AsciiDoc files.')
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
+    parser = argparse.ArgumentParser(
+        description='Archive unused AsciiDoc files.',
+        epilog='By default, automatically discovers all modules and assemblies directories in the repository.'
+    )
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
+    parser.add_argument('--commented', action='store_true', help='Include files that are referenced only in commented lines in the archive operation.')
+    parser.add_argument('--scan-dir', action='append', default=[], help='Specific directory to scan (can be used multiple times). If not specified, auto-discovers directories.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
     parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
     parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
     args = parser.parse_args()
 
-    scan_dirs = ['./modules', './modules/rn', './assemblies']
+    # Use provided scan directories or None for auto-discovery
+    scan_dirs = args.scan_dir if args.scan_dir else None
     archive_dir = './archive'
 
     exclude_dirs = list(args.exclude_dir)
     exclude_files = list(args.exclude_file)
-    
+
     if args.exclude_list:
         list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
         exclude_dirs.extend(list_dirs)
         exclude_files.extend(list_files)
 
-    find_unused_adoc(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+    find_unused_adoc(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files, args.commented)
 
 if __name__ == '__main__':
     main()

archive_unused_images.py

@@ -8,14 +8,21 @@ For full documentation and usage examples, see archive_unused_files.md in this d
 
 import argparse
 from doc_utils.unused_images import find_unused_images
+from doc_utils.version_check import check_version_on_startup
 from doc_utils.file_utils import parse_exclude_list_file
+from doc_utils.version import __version__
 
+from doc_utils.spinner import Spinner
 def main():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
     parser = argparse.ArgumentParser(description='Archive unused image files.')
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
+    parser.add_argument('--commented', action='store_true', help='Include images that are referenced only in commented lines in the archive operation.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
     parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
     parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
     args = parser.parse_args()
 
     scan_dirs = ['.']
@@ -23,13 +30,13 @@ def main():
 
     exclude_dirs = list(args.exclude_dir)
     exclude_files = list(args.exclude_file)
-    
+
     if args.exclude_list:
         list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
         exclude_dirs.extend(list_dirs)
         exclude_files.extend(list_files)
 
-    find_unused_images(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+    find_unused_images(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files, args.commented)
 
 if __name__ == '__main__':
     main()

callout_lib/__init__.py

@@ -0,0 +1,22 @@
+"""
+Callout Library - Shared modules for AsciiDoc callout conversion
+
+This library provides reusable components for converting AsciiDoc callouts
+to various formats including definition lists, bulleted lists, and inline comments.
+"""
+
+from .detector import CalloutDetector, CodeBlock, CalloutGroup, Callout
+from .converter_deflist import DefListConverter
+from .converter_bullets import BulletListConverter
+from .converter_comments import CommentConverter, LongCommentWarning
+
+__all__ = [
+    'CalloutDetector',
+    'CodeBlock',
+    'CalloutGroup',
+    'Callout',
+    'DefListConverter',
+    'BulletListConverter',
+    'CommentConverter',
+    'LongCommentWarning',
+]

callout_lib/converter_bullets.py

@@ -0,0 +1,103 @@
+"""
+Bulleted List Converter Module
+
+Converts callouts to bulleted list format following Red Hat style guide.
+"""
+
+import re
+from typing import List, Dict
+from .detector import CalloutGroup, Callout
+
+
+class BulletListConverter:
+    """Converts callouts to bulleted list format."""
+
+    # Pattern to detect user-replaceable values in angle brackets
+    USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
+
+    @staticmethod
+    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "") -> 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.
+
+        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
+        """
+        # 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:
+            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 = BulletListConverter.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 - strip whitespace before wrapping in backticks
+                term = f'`{code_line.strip()}`'
+
+            # 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

callout_lib/converter_comments.py

@@ -0,0 +1,295 @@
+"""
+Inline Comments Converter Module
+
+Converts callouts to inline comments within code blocks.
+"""
+
+import re
+from typing import List, Dict, Optional, Tuple
+from .detector import CalloutGroup, Callout
+
+
+class LongCommentWarning:
+    """Represents a warning about a comment that exceeds the length threshold."""
+    def __init__(self, callout_num: int, length: int, text: str, line_num: int = None):
+        self.callout_num = callout_num
+        self.length = length
+        self.text = text
+        self.line_num = line_num
+
+
+class CommentConverter:
+    """Converts callouts to inline comments in code."""
+
+    # Map of programming language identifiers to their comment syntax
+    COMMENT_SYNTAX = {
+        # Single-line comment languages
+        'java': '//',
+        'javascript': '//',
+        'js': '//',
+        'typescript': '//',
+        'ts': '//',
+        'c': '//',
+        'cpp': '//',
+        'c++': '//',
+        'csharp': '//',
+        'cs': '//',
+        'go': '//',
+        'rust': '//',
+        'swift': '//',
+        'kotlin': '//',
+        'scala': '//',
+        'groovy': '//',
+
+        # Hash comment languages
+        'python': '#',
+        'py': '#',
+        'ruby': '#',
+        'rb': '#',
+        'perl': '#',
+        'bash': '#',
+        'sh': '#',
+        'shell': '#',
+        'yaml': '#',
+        'yml': '#',
+        'properties': '#',
+        'r': '#',
+        'powershell': '#',
+        'ps1': '#',
+
+        # SQL variants
+        'sql': '--',
+        'plsql': '--',
+        'tsql': '--',
+
+        # Lua
+        'lua': '--',
+
+        # Lisp-like
+        'lisp': ';;',
+        'scheme': ';;',
+        'clojure': ';;',
+
+        # Markup languages
+        'html': '<!--',
+        'xml': '<!--',
+        'svg': '<!--',
+
+        # Other
+        'matlab': '%',
+        'tex': '%',
+        'latex': '%',
+    }
+
+    # Languages that need closing comment syntax
+    COMMENT_CLOSING = {
+        'html': '-->',
+        'xml': '-->',
+        'svg': '-->',
+    }
+
+    @staticmethod
+    def get_comment_syntax(language: Optional[str]) -> tuple[str, str]:
+        """
+        Get comment syntax for a given language.
+        Returns tuple of (opening, closing) comment markers.
+        For single-line comments, closing is empty string.
+
+        Args:
+            language: Language identifier (e.g., 'java', 'python')
+
+        Returns:
+            Tuple of (opening_marker, closing_marker)
+        """
+        if not language:
+            # Default to generic comment marker
+            return '#', ''
+
+        lang_lower = language.lower()
+        opening = CommentConverter.COMMENT_SYNTAX.get(lang_lower, '#')
+        closing = CommentConverter.COMMENT_CLOSING.get(lang_lower, '')
+
+        return opening, closing
+
+    @staticmethod
+    def format_comment(text: str, opening: str, closing: str = '') -> str:
+        """
+        Format text as a comment using the given markers.
+
+        Args:
+            text: Comment text
+            opening: Opening comment marker (e.g., '//', '#', '<!--')
+            closing: Closing comment marker (e.g., '-->')
+
+        Returns:
+            Formatted comment string
+        """
+        if closing:
+            return f'{opening} {text} {closing}'
+        else:
+            return f'{opening} {text}'
+
+    @staticmethod
+    def get_comment_length(explanation: Callout, opening: str, closing: str = '') -> int:
+        """
+        Calculate the total length of a comment including markers and text.
+
+        Args:
+            explanation: Callout explanation
+            opening: Opening comment marker
+            closing: Closing comment marker (if any)
+
+        Returns:
+            Total character length of the formatted comment
+        """
+        # Combine all explanation lines into single comment text
+        comment_parts = []
+        for exp_line in explanation.lines:
+            comment_parts.append(exp_line.strip())
+        comment_text = ' '.join(comment_parts)
+
+        # Add "Optional:" prefix if needed
+        if explanation.is_optional:
+            comment_text = f'Optional: {comment_text}'
+
+        # Calculate total length with markers
+        if closing:
+            total = len(f'{opening} {comment_text} {closing}')
+        else:
+            total = len(f'{opening} {comment_text}')
+
+        return total
+
+    @staticmethod
+    def shorten_comment(explanation: Callout) -> str:
+        """
+        Shorten a comment to its first sentence or clause.
+
+        Args:
+            explanation: Callout explanation
+
+        Returns:
+            Shortened comment text
+        """
+        # Get first line
+        first_line = explanation.lines[0] if explanation.lines else ''
+
+        # Find first sentence-ending punctuation
+        for delimiter in ['. ', '! ', '? ']:
+            if delimiter in first_line:
+                short = first_line.split(delimiter)[0] + delimiter.strip()
+                return short
+
+        # No sentence delimiter found, return first line
+        return first_line
+
+    @staticmethod
+    def check_comment_lengths(explanations: Dict[int, Callout], language: Optional[str] = None,
+                             max_length: int = 100) -> List[LongCommentWarning]:
+        """
+        Check if any comments exceed the maximum length threshold.
+
+        Args:
+            explanations: Dict of callout explanations
+            language: Programming language for comment syntax
+            max_length: Maximum allowed comment length (default: 100)
+
+        Returns:
+            List of LongCommentWarning objects for comments exceeding threshold
+        """
+        opening, closing = CommentConverter.get_comment_syntax(language)
+        warnings = []
+
+        for num, explanation in explanations.items():
+            length = CommentConverter.get_comment_length(explanation, opening, closing)
+            if length > max_length:
+                # Combine all lines for warning text
+                full_text = ' '.join(exp_line.strip() for exp_line in explanation.lines)
+                warnings.append(LongCommentWarning(num, length, full_text))
+
+        return warnings
+
+    @staticmethod
+    def convert(code_content: List[str], callout_groups: List[CalloutGroup],
+                explanations: Dict[int, Callout], language: Optional[str] = None,
+                max_length: Optional[int] = None, shorten_long: bool = False) -> Tuple[List[str], List[LongCommentWarning]]:
+        """
+        Convert callouts to inline comments within code.
+
+        This replaces callout markers (<1>, <2>, etc.) with actual comments containing
+        the explanation text. The comment syntax is determined by the code block's language.
+
+        Args:
+            code_content: Original code block content with callout markers
+            callout_groups: List of CalloutGroup objects (not used for inline conversion)
+            explanations: Dict mapping callout numbers to Callout objects
+            language: Programming language identifier for comment syntax
+            max_length: Maximum comment length before triggering warning (default: None = no limit)
+            shorten_long: If True, automatically shorten long comments to first sentence
+
+        Returns:
+            Tuple of (converted lines, list of LongCommentWarning objects)
+        """
+        opening, closing = CommentConverter.get_comment_syntax(language)
+        warnings = []
+
+        # Check for long comments if max_length specified
+        if max_length:
+            warnings = CommentConverter.check_comment_lengths(explanations, language, max_length)
+
+        # Pattern for callout number in code block
+        CALLOUT_IN_CODE = re.compile(r'<(\d+)>')
+
+        result_lines = []
+
+        for line in code_content:
+            # Find all callout markers on this line
+            matches = list(CALLOUT_IN_CODE.finditer(line))
+
+            if not matches:
+                # No callouts on this line - keep as-is
+                result_lines.append(line)
+                continue
+
+            # Process line with callouts
+            # Start from the end to maintain positions during replacement
+            modified_line = line
+
+            for match in reversed(matches):
+                callout_num = int(match.group(1))
+
+                if callout_num not in explanations:
+                    # Callout number not found in explanations - skip
+                    continue
+
+                explanation = explanations[callout_num]
+
+                # Check if we should shorten this comment
+                if shorten_long and any(w.callout_num == callout_num for w in warnings):
+                    # Use shortened version
+                    comment_text = CommentConverter.shorten_comment(explanation)
+                    if explanation.is_optional:
+                        comment_text = f'Optional: {comment_text}'
+                else:
+                    # Build comment text from explanation lines
+                    # For inline comments, combine multi-line explanations with spaces
+                    comment_parts = []
+                    for exp_line in explanation.lines:
+                        comment_parts.append(exp_line.strip())
+
+                    comment_text = ' '.join(comment_parts)
+
+                    # Add "Optional:" prefix if needed
+                    if explanation.is_optional:
+                        comment_text = f'Optional: {comment_text}'
+
+                # Format as comment
+                comment = CommentConverter.format_comment(comment_text, opening, closing)
+
+                # Replace the callout marker with the comment
+                start, end = match.span()
+                modified_line = modified_line[:start] + comment + modified_line[end:]
+
+            result_lines.append(modified_line)
+
+        return result_lines, warnings

callout_lib/converter_deflist.py

@@ -0,0 +1,134 @@
+"""
+Definition List Converter Module
+
+Converts callouts to AsciiDoc definition list format with "where:" prefix.
+"""
+
+import re
+from typing import List, Dict
+from .detector import CalloutGroup, Callout
+
+
+class DefListConverter:
+    """Converts callouts to definition list format."""
+
+    # Pattern to detect user-replaceable values in angle brackets
+    USER_VALUE_PATTERN = re.compile(r'(?<!<)<([a-zA-Z][^>]*)>')
+
+    @staticmethod
+    def convert(callout_groups: List[CalloutGroup], explanations: Dict[int, Callout], table_title: str = "",
+                definition_prefix: str = "") -> List[str]:
+        """
+        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 (+).
+
+        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:")
+            definition_prefix: Optional prefix to add before each definition (e.g., "Specifies ")
+
+        Returns:
+            List of strings representing the definition 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}, where:']
+        else:
+            lines = ['\nwhere:']
+
+        # 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
+
+            # COMMENTED OUT: User-replaceable value detection causes false positives
+            # with Java generics (e.g., <MyEntity, Integer>) and other valid syntax
+            # that uses angle brackets. Always use the full code line as the term.
+            #
+            # # 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 = DefListConverter.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 - strip whitespace before wrapping in backticks
+            #     term = f'`{code_line.strip()}`'
+
+            # Always use the full code line - strip whitespace before wrapping in backticks
+            term = f'`{code_line.strip()}`'
+
+            # Add blank line before each term
+            lines.append('')
+            lines.append(f'{term}::')
+
+            # Add explanations for all callouts in this group
+            for idx, callout_num in enumerate(callout_nums):
+                explanation = explanations[callout_num]
+
+                # 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
+                # 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 with optional prefix
+                    if line_idx == 0:
+                        # First line of definition
+                        if explanation.is_optional:
+                            # Optional marker takes precedence, then prefix
+                            if definition_prefix:
+                                lines.append(f'Optional. {definition_prefix}{line}')
+                            else:
+                                lines.append(f'Optional. {line}')
+                        elif definition_prefix:
+                            # Add prefix to first line
+                            lines.append(f'{definition_prefix}{line}')
+                        else:
+                            lines.append(line)
+                    else:
+                        lines.append(line)
+
+                    # Track that we've output content (not just conditionals)
+                    if not is_conditional:
+                        had_content = True
+
+        return lines