rolfedh-doc-utils 0.1.7__tar.gz → 0.1.9__tar.gz

{rolfedh_doc_utils-0.1.7/rolfedh_doc_utils.egg-info → rolfedh_doc_utils-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.7
+Version: 0.1.9
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -54,7 +54,11 @@ These tools can modify or delete files. **Always:**
 ### Install with pipx (Recommended)
 
 ```bash
+# Install
 pipx install rolfedh-doc-utils
+
+# Upgrade to latest version
+pipx upgrade rolfedh-doc-utils
 ```
 
 ### Alternative Installation
@@ -71,18 +75,37 @@ pip install -e .
 
 ## 🛠️ Available Tools
 
+**Note:** Commands use hyphens (`-`), while Python files use underscores (`_`). After installing with pipx, use the hyphenated commands directly.
+
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run .` |
+| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
 | **`check-scannability`** | Analyzes readability (sentence/paragraph length) | `check-scannability --max-words 25` |
-| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files --archive` |
-| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images --archive` |
+| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files` (preview)<br>`archive-unused-files --archive` (execute) |
+| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images` (preview)<br>`archive-unused-images --archive` (execute) |
 | **`find-unused-attributes`** | Identifies unused attribute definitions | `find-unused-attributes attributes.adoc` |
 
 ## 📖 Documentation
 
 Comprehensive documentation is available at **[rolfedh.github.io/doc-utils](https://rolfedh.github.io/doc-utils/)**
 
+### OpenShift-docs Example
+
+For OpenShift documentation repositories:
+
+```bash
+# Format spacing in specific directories
+format-asciidoc-spacing modules/
+format-asciidoc-spacing microshift_networking/
+
+# Preview changes first
+format-asciidoc-spacing --dry-run modules/networking/
+
+# Process specific file
+format-asciidoc-spacing modules/networking/about-networking.adoc
+```
+
 - [Getting Started Guide](https://rolfedh.github.io/doc-utils/getting-started)
 - [Tools Reference](https://rolfedh.github.io/doc-utils/tools/)
 - [Best Practices](https://rolfedh.github.io/doc-utils/best-practices)

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9}/README.md

@@ -21,7 +21,11 @@ These tools can modify or delete files. **Always:**
 ### Install with pipx (Recommended)
 
 ```bash
+# Install
 pipx install rolfedh-doc-utils
+
+# Upgrade to latest version
+pipx upgrade rolfedh-doc-utils
 ```
 
 ### Alternative Installation
@@ -38,18 +42,37 @@ pip install -e .
 
 ## 🛠️ Available Tools
 
+**Note:** Commands use hyphens (`-`), while Python files use underscores (`_`). After installing with pipx, use the hyphenated commands directly.
+
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run .` |
+| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
 | **`check-scannability`** | Analyzes readability (sentence/paragraph length) | `check-scannability --max-words 25` |
-| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files --archive` |
-| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images --archive` |
+| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files` (preview)<br>`archive-unused-files --archive` (execute) |
+| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images` (preview)<br>`archive-unused-images --archive` (execute) |
 | **`find-unused-attributes`** | Identifies unused attribute definitions | `find-unused-attributes attributes.adoc` |
 
 ## 📖 Documentation
 
 Comprehensive documentation is available at **[rolfedh.github.io/doc-utils](https://rolfedh.github.io/doc-utils/)**
 
+### OpenShift-docs Example
+
+For OpenShift documentation repositories:
+
+```bash
+# Format spacing in specific directories
+format-asciidoc-spacing modules/
+format-asciidoc-spacing microshift_networking/
+
+# Preview changes first
+format-asciidoc-spacing --dry-run modules/networking/
+
+# Process specific file
+format-asciidoc-spacing modules/networking/about-networking.adoc
+```
+
 - [Getting Started Guide](https://rolfedh.github.io/doc-utils/getting-started)
 - [Tools Reference](https://rolfedh.github.io/doc-utils/tools/)
 - [Best Practices](https://rolfedh.github.io/doc-utils/best-practices)

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9/doc_utils}/format_asciidoc_spacing.py

@@ -1,88 +1,75 @@
-#!/usr/bin/env python3
+"""
+Format AsciiDoc spacing - ensures blank lines after headings and around include directives.
 
-"""Format AsciiDoc spacing - ensures blank lines after headings and around include directives"""
+Core logic for formatting AsciiDoc files with proper spacing.
+"""
 
-import argparse
-import os
 import re
-import sys
 from pathlib import Path
 from typing import List, Tuple
 
 
-# Colors for output
-class Colors:
-    RED = '\033[0;31m'
-    GREEN = '\033[0;32m'
-    YELLOW = '\033[1;33m'
-    NC = '\033[0m'  # No Color
-
-
-def print_colored(message: str, color: str = Colors.NC) -> None:
-    """Print message with color"""
-    print(f"{color}{message}{Colors.NC}")
-
-
-def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> bool:
+def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> Tuple[bool, List[str]]:
     """
     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
+        Tuple of (changes_made, messages) where messages is a list of verbose output
     """
+    messages = []
+
     if verbose:
-        print(f"Processing: {file_path}")
-    
+        messages.append(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
-    
+        raise IOError(f"Error reading {file_path}: {e}")
+
     # 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 
+            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")
+                    messages.append("  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 
+            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")
-        
+                    messages.append("  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):
@@ -91,17 +78,17 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
         # 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 
+            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}")
-        
+                    messages.append(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
@@ -111,16 +98,16 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
                 # 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 
+                    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")
+                            messages.append("  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
@@ -130,16 +117,16 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
                 # 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 
+                    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")
+                            messages.append("  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
@@ -148,7 +135,7 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
             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
@@ -156,45 +143,45 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
                     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 
+                        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}")
-                
+                                messages.append(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 
+                    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}")
-        
+                            messages.append(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
@@ -207,112 +194,29 @@ def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False)
                     # 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:
+
+        if not dry_run:
             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
+                raise IOError(f"Error writing {file_path}: {e}")
     else:
         if verbose:
-            print("  No changes needed")
-    
-    return changes_made
+            messages.append("  No changes needed")
+
+    return changes_made, messages
 
 
 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(
-        description="Format AsciiDoc files to ensure proper spacing",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Format AsciiDoc files to ensure proper spacing:
-- Blank line after headings (=, ==, ===, etc.)
-- Blank lines around include:: directives
-
-Examples:
-  %(prog)s                                    # Process all .adoc files in current directory
-  %(prog)s modules/                          # Process all .adoc files in modules/
-  %(prog)s assemblies/my-guide.adoc          # Process single file
-  %(prog)s --dry-run modules/               # Preview changes without modifying
-        """
-    )
-    
-    parser.add_argument(
-        'path',
-        nargs='?',
-        default='.',
-        help='File or directory to process (default: current directory)'
-    )
-    parser.add_argument(
-        '-n', '--dry-run',
-        action='store_true',
-        help='Show what would be changed without modifying files'
-    )
-    parser.add_argument(
-        '-v', '--verbose',
-        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:
-        print(f"Processed 0 AsciiDoc file(s)")
-        print("AsciiDoc spacing formatting complete!")
-        return
-    
-    # Process each file
-    files_processed = 0
-    for file_path in adoc_files:
-        try:
-            process_file(file_path, args.dry_run, args.verbose)
-            files_processed += 1
-        except KeyboardInterrupt:
-            print_colored("\nOperation cancelled by user", Colors.YELLOW)
-            sys.exit(1)
-        except Exception as e:
-            print_colored(f"Unexpected error processing {file_path}: {e}", Colors.RED)
-    
-    print(f"Processed {files_processed} AsciiDoc file(s)")
-    print("AsciiDoc spacing formatting complete!")
-
-
-if __name__ == "__main__":
-    main()
+
+    return adoc_files

rolfedh_doc_utils-0.1.9/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

rolfedh_doc_utils-0.1.9/format_asciidoc_spacing.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+format-asciidoc-spacing - Format AsciiDoc spacing.
+
+Ensures blank lines after headings and around include directives.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from doc_utils.format_asciidoc_spacing import process_file, find_adoc_files
+
+
+# Colors for output
+class Colors:
+    RED = '\033[0;31m'
+    GREEN = '\033[0;32m'
+    YELLOW = '\033[1;33m'
+    NC = '\033[0m'  # No Color
+
+
+def print_colored(message: str, color: str = Colors.NC) -> None:
+    """Print message with color"""
+    print(f"{color}{message}{Colors.NC}")
+
+
+def main():
+    """Main entry point"""
+    parser = argparse.ArgumentParser(
+        description="Format AsciiDoc files to ensure proper spacing",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Format AsciiDoc files to ensure proper spacing:
+- Blank line after headings (=, ==, ===, etc.)
+- Blank lines around include:: directives
+
+Examples:
+  %(prog)s                                    # Process all .adoc files in current directory
+  %(prog)s modules/                          # Process all .adoc files in modules/
+  %(prog)s assemblies/my-guide.adoc          # Process single file
+  %(prog)s --dry-run modules/               # Preview changes without modifying
+        """
+    )
+
+    parser.add_argument(
+        'path',
+        nargs='?',
+        default='.',
+        help='File or directory to process (default: current directory)'
+    )
+    parser.add_argument(
+        '-n', '--dry-run',
+        action='store_true',
+        help='Show what would be changed without modifying files'
+    )
+    parser.add_argument(
+        '-v', '--verbose',
+        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:
+            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!")
+
+
+if __name__ == "__main__":
+    main()

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.7"
+version = "0.1.9"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -20,10 +20,11 @@ archive-unused-files = "archive_unused_files:main"
 archive-unused-images = "archive_unused_images:main"
 find-unused-attributes = "find_unused_attributes:main"
 format-asciidoc-spacing = "format_asciidoc_spacing:main"
+replace-link-attributes = "replace_link_attributes:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["doc_utils*"]
 
 [tool.setuptools]
-py-modules = ["find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing"]
+py-modules = ["find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes"]

rolfedh_doc_utils-0.1.9/replace_link_attributes.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+replace-link-attributes - Replace AsciiDoc attributes within link URLs with their actual values.
+
+This script 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 argparse
+import sys
+from pathlib import Path
+from typing import Optional
+
+from doc_utils.replace_link_attributes import (
+    find_attributes_files,
+    load_attributes,
+    resolve_nested_attributes,
+    replace_link_attributes_in_file,
+    find_adoc_files
+)
+
+
+def prompt_for_attributes_file(attributes_files: list[Path]) -> Optional[Path]:
+    """Prompt user to select or specify attributes file."""
+    if not attributes_files:
+        print("No attributes.adoc files found in the repository.")
+        response = input("Enter the path to your attributes.adoc file (or 'q' to quit): ").strip()
+        if response.lower() == 'q':
+            return None
+        path = Path(response)
+        if path.exists() and path.is_file():
+            return path
+        else:
+            print(f"Error: File not found: {response}")
+            return None
+
+    if len(attributes_files) == 1:
+        file_path = attributes_files[0]
+        response = input(f"Found attributes file: {file_path}\nUse this file? (y/n/q): ").strip().lower()
+        if response == 'y':
+            return file_path
+        elif response == 'q':
+            return None
+        else:
+            response = input("Enter the path to your attributes.adoc file (or 'q' to quit): ").strip()
+            if response.lower() == 'q':
+                return None
+            path = Path(response)
+            if path.exists() and path.is_file():
+                return path
+            else:
+                print(f"Error: File not found: {response}")
+                return None
+
+    # Multiple files found
+    print("\nFound multiple attributes.adoc files:")
+    for i, file_path in enumerate(attributes_files, 1):
+        print(f"  {i}. {file_path}")
+    print(f"  {len(attributes_files) + 1}. Enter custom path")
+
+    while True:
+        response = input(f"\nSelect option (1-{len(attributes_files) + 1}) or 'q' to quit: ").strip()
+        if response.lower() == 'q':
+            return None
+
+        try:
+            choice = int(response)
+            if 1 <= choice <= len(attributes_files):
+                return attributes_files[choice - 1]
+            elif choice == len(attributes_files) + 1:
+                response = input("Enter the path to your attributes.adoc file: ").strip()
+                path = Path(response)
+                if path.exists() and path.is_file():
+                    return path
+                else:
+                    print(f"Error: File not found: {response}")
+            else:
+                print(f"Invalid choice. Please enter a number between 1 and {len(attributes_files) + 1}")
+        except ValueError:
+            print("Invalid input. Please enter a number.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Replace AsciiDoc attributes within link macros with their actual values.'
+    )
+    parser.add_argument(
+        '--dry-run', '-n',
+        action='store_true',
+        help='Show what would be changed without making actual modifications'
+    )
+    parser.add_argument(
+        '--path', '-p',
+        type=str,
+        default='.',
+        help='Repository path to search (default: current directory)'
+    )
+    parser.add_argument(
+        '--attributes-file', '-a',
+        type=str,
+        help='Path to attributes.adoc file (skips interactive selection)'
+    )
+
+    args = parser.parse_args()
+
+    # Determine repository root
+    repo_root = Path(args.path).resolve()
+
+    if not repo_root.exists() or not repo_root.is_dir():
+        print(f"Error: Directory not found: {repo_root}")
+        sys.exit(1)
+
+    print(f"{'DRY RUN MODE - ' if args.dry_run else ''}Searching in: {repo_root}")
+
+    # Find or get attributes file
+    if args.attributes_file:
+        attributes_file = Path(args.attributes_file)
+        if not attributes_file.exists():
+            print(f"Error: Specified attributes file not found: {attributes_file}")
+            sys.exit(1)
+    else:
+        print("\nSearching for attributes.adoc files...")
+        attributes_files = find_attributes_files(repo_root)
+        attributes_file = prompt_for_attributes_file(attributes_files)
+
+        if not attributes_file:
+            print("Operation cancelled.")
+            sys.exit(0)
+
+    print(f"\nLoading attributes from: {attributes_file}")
+    attributes = load_attributes(attributes_file)
+
+    if not attributes:
+        print("No attributes found in the file.")
+        sys.exit(1)
+
+    print(f"Found {len(attributes)} attributes")
+
+    # Resolve nested references
+    print("Resolving nested attribute references...")
+    attributes = resolve_nested_attributes(attributes)
+
+    # Find all AsciiDoc files
+    print(f"\nSearching for *.adoc files in {repo_root}")
+    adoc_files = find_adoc_files(repo_root)
+
+    # Exclude the attributes file itself
+    adoc_files = [f for f in adoc_files if f != attributes_file]
+
+    print(f"Found {len(adoc_files)} AsciiDoc files to process")
+
+    if args.dry_run:
+        print("\n*** DRY RUN MODE - No files will be modified ***\n")
+
+    # Process each file
+    total_replacements = 0
+    files_modified = 0
+
+    for file_path in adoc_files:
+        replacements = replace_link_attributes_in_file(file_path, attributes, args.dry_run)
+        if replacements > 0:
+            rel_path = file_path.relative_to(repo_root)
+            prefix = "[DRY RUN] " if args.dry_run else ""
+            print(f"  {prefix}Modified {rel_path}: {replacements} replacements")
+            total_replacements += replacements
+            files_modified += 1
+
+    # Summary
+    print(f"\nSummary:")
+    if args.dry_run:
+        print(f"  Would modify {files_modified} files")
+        print(f"  Would make {total_replacements} replacements")
+        print("\nRun without --dry-run to apply changes.")
+    else:
+        print(f"  Total files modified: {files_modified}")
+        print(f"  Total replacements: {total_replacements}")
+
+        if total_replacements == 0:
+            print("\nNo attribute references found within link macros.")
+        else:
+            print("\nReplacement complete!")
+
+
+if __name__ == '__main__':
+    main()

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9/rolfedh_doc_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.7
+Version: 0.1.9
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License
@@ -54,7 +54,11 @@ These tools can modify or delete files. **Always:**
 ### Install with pipx (Recommended)
 
 ```bash
+# Install
 pipx install rolfedh-doc-utils
+
+# Upgrade to latest version
+pipx upgrade rolfedh-doc-utils
 ```
 
 ### Alternative Installation
@@ -71,18 +75,37 @@ pip install -e .
 
 ## 🛠️ Available Tools
 
+**Note:** Commands use hyphens (`-`), while Python files use underscores (`_`). After installing with pipx, use the hyphenated commands directly.
+
 | Tool | Description | Usage |
 |------|-------------|-------|
-| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run .` |
+| **`replace-link-attributes`** | Resolves Vale LinkAttribute violations by replacing attributes in link URLs | `replace-link-attributes --dry-run` |
+| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run modules/` |
 | **`check-scannability`** | Analyzes readability (sentence/paragraph length) | `check-scannability --max-words 25` |
-| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files --archive` |
-| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images --archive` |
+| **`archive-unused-files`** | Finds and archives unreferenced .adoc files | `archive-unused-files` (preview)<br>`archive-unused-files --archive` (execute) |
+| **`archive-unused-images`** | Finds and archives unreferenced images | `archive-unused-images` (preview)<br>`archive-unused-images --archive` (execute) |
 | **`find-unused-attributes`** | Identifies unused attribute definitions | `find-unused-attributes attributes.adoc` |
 
 ## 📖 Documentation
 
 Comprehensive documentation is available at **[rolfedh.github.io/doc-utils](https://rolfedh.github.io/doc-utils/)**
 
+### OpenShift-docs Example
+
+For OpenShift documentation repositories:
+
+```bash
+# Format spacing in specific directories
+format-asciidoc-spacing modules/
+format-asciidoc-spacing microshift_networking/
+
+# Preview changes first
+format-asciidoc-spacing --dry-run modules/networking/
+
+# Process specific file
+format-asciidoc-spacing modules/networking/about-networking.adoc
+```
+
 - [Getting Started Guide](https://rolfedh.github.io/doc-utils/getting-started)
 - [Tools Reference](https://rolfedh.github.io/doc-utils/tools/)
 - [Best Practices](https://rolfedh.github.io/doc-utils/best-practices)

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -6,9 +6,12 @@ check_scannability.py
 find_unused_attributes.py
 format_asciidoc_spacing.py
 pyproject.toml
+replace_link_attributes.py
 setup.py
 doc_utils/__init__.py
 doc_utils/file_utils.py
+doc_utils/format_asciidoc_spacing.py
+doc_utils/replace_link_attributes.py
 doc_utils/scannability.py
 doc_utils/topic_map_parser.py
 doc_utils/unused_adoc.py

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9}/rolfedh_doc_utils.egg-info/entry_points.txt

@@ -4,3 +4,4 @@ archive-unused-images = archive_unused_images:main
 check-scannability = check_scannability:main
 find-unused-attributes = find_unused_attributes:main
 format-asciidoc-spacing = format_asciidoc_spacing:main
+replace-link-attributes = replace_link_attributes:main

{rolfedh_doc_utils-0.1.7 → rolfedh_doc_utils-0.1.9}/rolfedh_doc_utils.egg-info/top_level.txt

@@ -4,3 +4,4 @@ check_scannability
 doc_utils
 find_unused_attributes
 format_asciidoc_spacing
+replace_link_attributes