rolfedh-doc-utils 0.1.8__py3-none-any.whl → 0.1.10__py3-none-any.whl

doc_utils/replace_link_attributes.py

@@ -0,0 +1,168 @@
+"""
+Replace AsciiDoc attributes within link URLs with their actual values.
+
+This module finds and replaces attribute references (like {attribute-name}) that appear
+in the URL portion of AsciiDoc link macros (link: and xref:) with their resolved values
+from attributes.adoc. Link text is preserved unchanged.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple, Optional
+
+
+def find_attributes_files(root_dir: Path) -> List[Path]:
+    """Find all attributes.adoc files in the repository."""
+    attributes_files = []
+
+    for path in root_dir.rglob('**/attributes.adoc'):
+        # Skip hidden directories and common build directories
+        parts = path.parts
+        if any(part.startswith('.') or part in ['target', 'build', 'node_modules'] for part in parts):
+            continue
+        attributes_files.append(path)
+
+    return attributes_files
+
+
+def load_attributes(attributes_file: Path) -> Dict[str, str]:
+    """Load attribute definitions from an attributes.adoc file."""
+    attributes = {}
+
+    with open(attributes_file, 'r', encoding='utf-8') as f:
+        for line in f:
+            # Match attribute definitions
+            # Format: :attribute-name: value
+            match = re.match(r'^:([a-zA-Z0-9_-]+):\s*(.*)$', line)
+            if match:
+                attr_name = match.group(1)
+                attr_value = match.group(2).strip()
+                attributes[attr_name] = attr_value
+
+    return attributes
+
+
+def resolve_nested_attributes(attributes: Dict[str, str], max_iterations: int = 10) -> Dict[str, str]:
+    """Resolve nested attribute references within attribute values."""
+    for _ in range(max_iterations):
+        changes_made = False
+
+        for attr_name, attr_value in attributes.items():
+            # Find all attribute references in the value
+            refs = re.findall(r'\{([a-zA-Z0-9_-]+)\}', attr_value)
+
+            for ref in refs:
+                if ref in attributes:
+                    new_value = attr_value.replace(f'{{{ref}}}', attributes[ref])
+                    if new_value != attr_value:
+                        attributes[attr_name] = new_value
+                        changes_made = True
+                        attr_value = new_value
+
+        if not changes_made:
+            break
+
+    return attributes
+
+
+def replace_link_attributes_in_file(file_path: Path, attributes: Dict[str, str], dry_run: bool = False) -> int:
+    """Replace attribute references within link macros in a single file."""
+    with open(file_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    original_content = content
+    replacement_count = 0
+
+    # Find all link macros containing attributes in the URL portion only
+    # Match link: and xref: macros, capturing URL and text separately
+    link_patterns = [
+        # link:url[text] - replace only in URL portion
+        (r'link:([^[\]]*)\[([^\]]*)\]', 'link'),
+        # xref:target[text] - replace only in target portion
+        (r'xref:([^[\]]*)\[([^\]]*)\]', 'xref'),
+        # link:url[] or xref:target[] - replace in URL/target portion
+        (r'(link|xref):([^[\]]*)\[\]', 'empty_text')
+    ]
+
+    for pattern, link_type in link_patterns:
+        matches = list(re.finditer(pattern, content))
+
+        # Process matches in reverse order to maintain string positions
+        for match in reversed(matches):
+            if link_type == 'empty_text':
+                # For links with empty text []
+                macro_type = match.group(1)  # 'link' or 'xref'
+                url_part = match.group(2)
+                text_part = ''
+
+                # Check if URL contains attributes
+                if re.search(r'\{[a-zA-Z0-9_-]+\}', url_part):
+                    modified_url = url_part
+
+                    # Replace attributes only in URL
+                    attr_matches = re.findall(r'\{([a-zA-Z0-9_-]+)\}', url_part)
+                    for attr_name in attr_matches:
+                        if attr_name in attributes:
+                            attr_pattern = re.escape(f'{{{attr_name}}}')
+                            modified_url = re.sub(attr_pattern, attributes[attr_name], modified_url)
+                            replacement_count += 1
+
+                    if modified_url != url_part:
+                        # Reconstruct the link with modified URL
+                        modified = f'{macro_type}:{modified_url}[]'
+                        start = match.start()
+                        end = match.end()
+                        content = content[:start] + modified + content[end:]
+            else:
+                # For links with text
+                url_part = match.group(1)
+                text_part = match.group(2)
+
+                # Check if URL contains attributes
+                if re.search(r'\{[a-zA-Z0-9_-]+\}', url_part):
+                    modified_url = url_part
+
+                    # Replace attributes only in URL
+                    attr_matches = re.findall(r'\{([a-zA-Z0-9_-]+)\}', url_part)
+                    for attr_name in attr_matches:
+                        if attr_name in attributes:
+                            attr_pattern = re.escape(f'{{{attr_name}}}')
+                            modified_url = re.sub(attr_pattern, attributes[attr_name], modified_url)
+                            replacement_count += 1
+
+                    if modified_url != url_part:
+                        # Reconstruct the link with modified URL but original text
+                        if link_type == 'link':
+                            modified = f'link:{modified_url}[{text_part}]'
+                        else:  # xref
+                            modified = f'xref:{modified_url}[{text_part}]'
+
+                        start = match.start()
+                        end = match.end()
+                        content = content[:start] + modified + content[end:]
+
+    # Write changes if not in dry-run mode
+    if content != original_content:
+        if not dry_run:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)
+
+        return replacement_count
+
+    return 0
+
+
+def find_adoc_files(root_dir: Path, exclude_dirs: Optional[set] = None) -> List[Path]:
+    """Find all *.adoc files in the repository."""
+    if exclude_dirs is None:
+        exclude_dirs = {'.git', 'target', 'build', 'node_modules'}
+
+    adoc_files = []
+
+    for path in root_dir.rglob('*.adoc'):
+        # Check if any part of the path is in exclude_dirs
+        parts = set(path.parts)
+        if not parts.intersection(exclude_dirs):
+            adoc_files.append(path)
+
+    return adoc_files

extract_link_attributes.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""
+Extract link and xref macros containing attributes into attribute definitions.
+
+This tool finds all link: and xref: macros whose URLs contain attributes,
+creates attribute definitions for them, and replaces the macros with
+attribute references.
+"""
+
+import argparse
+import sys
+from doc_utils.extract_link_attributes import extract_link_attributes
+
+
+def main():
+    """Main entry point for the extract-link-attributes CLI tool."""
+    parser = argparse.ArgumentParser(
+        description='Extract link and xref macros containing attributes into attribute definitions',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive mode with auto-discovery
+  extract-link-attributes
+
+  # Specify attribute file
+  extract-link-attributes --attributes-file common-attributes.adoc
+
+  # Non-interactive mode (uses most common link text)
+  extract-link-attributes --non-interactive
+
+  # Dry run to preview changes
+  extract-link-attributes --dry-run
+
+  # Scan specific directories
+  extract-link-attributes --scan-dir modules --scan-dir assemblies
+        """
+    )
+
+    parser.add_argument(
+        '--attributes-file',
+        help='Path to the attributes file to update (auto-discovered if not specified)'
+    )
+
+    parser.add_argument(
+        '--scan-dir',
+        action='append',
+        help='Directory to scan for .adoc files (can be used multiple times, default: current directory)'
+    )
+
+    parser.add_argument(
+        '--non-interactive',
+        action='store_true',
+        help='Non-interactive mode: automatically use most common link text for variations'
+    )
+
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Preview changes without modifying files'
+    )
+
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Enable verbose output'
+    )
+
+    args = parser.parse_args()
+
+    try:
+        success = extract_link_attributes(
+            attributes_file=args.attributes_file,
+            scan_dirs=args.scan_dir,
+            interactive=not args.non_interactive,
+            dry_run=args.dry_run
+        )
+
+        if not success:
+            sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\nOperation cancelled.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

format_asciidoc_spacing.py

@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
+"""
+format-asciidoc-spacing - Format AsciiDoc spacing.
 
-"""Format AsciiDoc spacing - ensures blank lines after headings and around include directives"""
+Ensures blank lines after headings and around include directives.
+"""
 
 import argparse
-import os
-import re
 import sys
 from pathlib import Path
-from typing import List, Tuple
+
+from doc_utils.format_asciidoc_spacing import process_file, find_adoc_files
 
 
 # Colors for output
@@ -23,224 +25,6 @@ def print_colored(message: str, color: str = Colors.NC) -> None:
     print(f"{color}{message}{Colors.NC}")
 
 
-def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> bool:
-    """
-    Process a single AsciiDoc file to fix spacing issues.
-    
-    Args:
-        file_path: Path to the file to process
-        dry_run: If True, show what would be changed without modifying
-        verbose: If True, show detailed output
-    
-    Returns:
-        True if changes were made (or would be made in dry-run), False otherwise
-    """
-    if verbose:
-        print(f"Processing: {file_path}")
-    
-    try:
-        with open(file_path, 'r', encoding='utf-8') as f:
-            lines = f.readlines()
-    except (IOError, UnicodeDecodeError) as e:
-        print_colored(f"Error reading {file_path}: {e}", Colors.RED)
-        return False
-    
-    # Remove trailing newlines from lines for processing
-    lines = [line.rstrip('\n\r') for line in lines]
-    
-    new_lines = []
-    changes_made = False
-    in_block = False  # Track if we're inside a block (admonition, listing, etc.)
-    in_conditional = False  # Track if we're inside a conditional block
-    
-    for i, current_line in enumerate(lines):
-        prev_line = lines[i-1] if i > 0 else ""
-        next_line = lines[i+1] if i + 1 < len(lines) else ""
-        
-        # Check for conditional start (ifdef:: or ifndef::)
-        if re.match(r'^(ifdef::|ifndef::)', current_line):
-            in_conditional = True
-            # Add blank line before conditional if needed
-            if (prev_line and 
-                not re.match(r'^\s*$', prev_line) and
-                not re.match(r'^(ifdef::|ifndef::|endif::)', prev_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    print(f"  Added blank line before conditional block")
-            new_lines.append(current_line)
-        
-        # Check for conditional end (endif::)
-        elif re.match(r'^endif::', current_line):
-            new_lines.append(current_line)
-            in_conditional = False
-            # Add blank line after conditional if needed
-            if (next_line and 
-                not re.match(r'^\s*$', next_line) and
-                not re.match(r'^(ifdef::|ifndef::|endif::)', next_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    print(f"  Added blank line after conditional block")
-        
-        # Check for block delimiters (====, ----, ...., ____)
-        # These are used for admonitions, listing blocks, literal blocks, etc.
-        elif re.match(r'^(====+|----+|\.\.\.\.+|____+)$', current_line):
-            in_block = not in_block  # Toggle block state
-            new_lines.append(current_line)
-        # Check if current line is a heading (but not if we're in a block)
-        elif not in_block and re.match(r'^=+\s+', current_line):
-            new_lines.append(current_line)
-            
-            # Check if next line is not empty and not another heading
-            if (next_line and 
-                not re.match(r'^=+\s+', next_line) and 
-                not re.match(r'^\s*$', next_line)):
-                new_lines.append("")
-                changes_made = True
-                if verbose:
-                    truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                    print(f"  Added blank line after heading: {truncated}")
-        
-        # Check if current line is a comment (AsciiDoc comments start with //)
-        elif re.match(r'^//', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if next line is an include directive
-                if next_line and re.match(r'^include::', next_line):
-                    # This comment belongs to the include, add blank line before comment if needed
-                    if (prev_line and 
-                        not re.match(r'^\s*$', prev_line) and 
-                        not re.match(r'^//', prev_line) and
-                        not re.match(r'^:', prev_line)):  # Don't add if previous is attribute
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            print(f"  Added blank line before comment above include")
-                new_lines.append(current_line)
-        
-        # Check if current line is an attribute (starts with :)
-        elif re.match(r'^:', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if next line is an include directive
-                if next_line and re.match(r'^include::', next_line):
-                    # This attribute belongs to the include, add blank line before attribute if needed
-                    if (prev_line and 
-                        not re.match(r'^\s*$', prev_line) and 
-                        not re.match(r'^//', prev_line) and
-                        not re.match(r'^:', prev_line)):  # Don't add if previous is comment or attribute
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            print(f"  Added blank line before attribute above include")
-                new_lines.append(current_line)
-        
-        # Check if current line is an include directive
-        elif re.match(r'^include::', current_line):
-            # Skip special handling if we're inside a conditional block
-            if in_conditional:
-                new_lines.append(current_line)
-            else:
-                # Check if this is an attribute include (contains "attribute" in the path)
-                is_attribute_include = 'attribute' in current_line.lower()
-                
-                # Check if this appears near the top of the file (within first 10 lines after H1)
-                # Find the H1 heading position
-                h1_position = -1
-                for j in range(min(i, 10)):  # Look back up to 10 lines or to current position
-                    if re.match(r'^=\s+', lines[j]):  # H1 heading starts with single =
-                        h1_position = j
-                        break
-                
-                # If this is an attribute include near the H1 heading, don't add surrounding blank lines
-                is_near_h1 = h1_position >= 0 and (i - h1_position) <= 2
-                
-                # Check if previous line is a comment or attribute (which belongs to this include)
-                has_comment_above = prev_line and re.match(r'^//', prev_line)
-                has_attribute_above = prev_line and re.match(r'^:', prev_line)
-                
-                # If it's an attribute include near H1, only the heading's blank line is needed
-                if not (is_attribute_include and is_near_h1):
-                    # Don't add blank line if there's a comment or attribute above (it was handled by the comment/attribute logic)
-                    if not has_comment_above and not has_attribute_above:
-                        # Add blank line before include if previous line is not empty and not an include
-                        if (prev_line and 
-                            not re.match(r'^\s*$', prev_line) and 
-                            not re.match(r'^include::', prev_line)):
-                            new_lines.append("")
-                            changes_made = True
-                            if verbose:
-                                truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                                print(f"  Added blank line before include: {truncated}")
-                
-                new_lines.append(current_line)
-                
-                # If it's an attribute include near H1, don't add blank line after
-                if not (is_attribute_include and is_near_h1):
-                    # Add blank line after include if next line exists and is not empty and not an include
-                    if (next_line and 
-                        not re.match(r'^\s*$', next_line) and 
-                        not re.match(r'^include::', next_line)):
-                        new_lines.append("")
-                        changes_made = True
-                        if verbose:
-                            truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
-                            print(f"  Added blank line after include: {truncated}")
-        
-        else:
-            new_lines.append(current_line)
-    
-    # Apply changes if any were made
-    if changes_made:
-        # Clean up any consecutive blank lines we may have added
-        cleaned_lines = []
-        for i, line in enumerate(new_lines):
-            # Check if this is a blank line we're about to add
-            if line == "":
-                # Check if the previous line is also a blank line
-                if i > 0 and cleaned_lines and cleaned_lines[-1] == "":
-                    # Skip this blank line as we already have one
-                    continue
-            cleaned_lines.append(line)
-        
-        if dry_run:
-            print_colored(f"Would modify: {file_path}", Colors.YELLOW)
-        else:
-            try:
-                with open(file_path, 'w', encoding='utf-8') as f:
-                    for line in cleaned_lines:
-                        f.write(line + '\n')
-                print_colored(f"Modified: {file_path}", Colors.GREEN)
-            except IOError as e:
-                print_colored(f"Error writing {file_path}: {e}", Colors.RED)
-                return False
-    else:
-        if verbose:
-            print("  No changes needed")
-    
-    return changes_made
-
-
-def find_adoc_files(path: Path) -> List[Path]:
-    """Find all .adoc files in the given path"""
-    adoc_files = []
-    
-    if path.is_file():
-        if path.suffix == '.adoc':
-            adoc_files.append(path)
-        else:
-            print_colored(f"Warning: {path} is not an AsciiDoc file (.adoc)", Colors.YELLOW)
-    elif path.is_dir():
-        adoc_files = list(path.rglob('*.adoc'))
-    
-    return adoc_files
-
-
 def main():
     """Main entry point"""
     parser = argparse.ArgumentParser(
@@ -258,7 +42,7 @@ Examples:
   %(prog)s --dry-run modules/               # Preview changes without modifying
         """
     )
-    
+
     parser.add_argument(
         'path',
         nargs='?',
@@ -275,42 +59,68 @@ Examples:
         action='store_true',
         help='Show detailed output'
     )
-    
+
     args = parser.parse_args()
-    
+
     # Convert path to Path object
     target_path = Path(args.path)
-    
+
     # Check if path exists
     if not target_path.exists():
         print_colored(f"Error: Path does not exist: {target_path}", Colors.RED)
         sys.exit(1)
-    
+
     # Display dry-run mode message
     if args.dry_run:
         print_colored("DRY RUN MODE - No files will be modified", Colors.YELLOW)
-    
+
     # Find all AsciiDoc files
     adoc_files = find_adoc_files(target_path)
-    
+
     if not adoc_files:
+        if target_path.is_file():
+            print_colored(f"Warning: {target_path} is not an AsciiDoc file (.adoc)", Colors.YELLOW)
         print(f"Processed 0 AsciiDoc file(s)")
         print("AsciiDoc spacing formatting complete!")
         return
-    
+
     # Process each file
     files_processed = 0
+    files_modified = 0
+
     for file_path in adoc_files:
         try:
-            process_file(file_path, args.dry_run, args.verbose)
+            changes_made, messages = process_file(file_path, args.dry_run, args.verbose)
+
+            # Print verbose messages
+            if args.verbose:
+                for msg in messages:
+                    print(msg)
+
+            if changes_made:
+                files_modified += 1
+                if args.dry_run:
+                    print_colored(f"Would modify: {file_path}", Colors.YELLOW)
+                else:
+                    print_colored(f"Modified: {file_path}", Colors.GREEN)
+            elif args.verbose:
+                print(f"  No changes needed for: {file_path}")
+
             files_processed += 1
+
         except KeyboardInterrupt:
             print_colored("\nOperation cancelled by user", Colors.YELLOW)
             sys.exit(1)
+        except IOError as e:
+            print_colored(f"{e}", Colors.RED)
         except Exception as e:
             print_colored(f"Unexpected error processing {file_path}: {e}", Colors.RED)
-    
+
     print(f"Processed {files_processed} AsciiDoc file(s)")
+    if args.dry_run and files_modified > 0:
+        print(f"Would modify {files_modified} file(s)")
+    elif files_modified > 0:
+        print(f"Modified {files_modified} file(s)")
     print("AsciiDoc spacing formatting complete!")