rolfedh-doc-utils 0.1.6__py3-none-any.whl → 0.1.7__py3-none-any.whl

format_asciidoc_spacing.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+
+"""Format AsciiDoc spacing - 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
+
+
+# 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:
+    """
+    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(
+        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()

rolfedh_doc_utils-0.1.7.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: rolfedh-doc-utils
+Version: 0.1.7
+Summary: CLI tools for AsciiDoc documentation projects
+Author: Rolfe Dlugy-Hegwer
+License: MIT License
+        
+        Copyright (c) 2025 Rolfe Dlugy-Hegwer
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# doc-utils
+
+[![PyPI version](https://badge.fury.io/py/rolfedh-doc-utils.svg)](https://pypi.org/project/rolfedh-doc-utils/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/github/license/rolfedh/doc-utils)](https://github.com/rolfedh/doc-utils/blob/main/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-brightgreen)](https://rolfedh.github.io/doc-utils/)
+
+Python CLI tools for maintaining clean, consistent AsciiDoc documentation repositories.
+
+📚 **[View Full Documentation](https://rolfedh.github.io/doc-utils/)** | 📦 **[PyPI Package](https://pypi.org/project/rolfedh-doc-utils/)** | 🐙 **[GitHub](https://github.com/rolfedh/doc-utils)**
+
+## ⚠️ Safety First
+
+These tools can modify or delete files. **Always:**
+- Work in a git branch (never main/master)
+- Review changes with `git diff`
+- Test documentation builds after changes
+
+## 🚀 Quick Start
+
+### Install with pipx (Recommended)
+
+```bash
+pipx install rolfedh-doc-utils
+```
+
+### Alternative Installation
+
+```bash
+# With pip user flag
+pip install --user rolfedh-doc-utils
+
+# For development
+git clone https://github.com/rolfedh/doc-utils.git
+cd doc-utils
+pip install -e .
+```
+
+## 🛠️ Available Tools
+
+| Tool | Description | Usage |
+|------|-------------|-------|
+| **`format-asciidoc-spacing`** | Standardizes spacing after headings and around includes | `format-asciidoc-spacing --dry-run .` |
+| **`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` |
+| **`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/)**
+
+- [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)
+- [Contributing](https://rolfedh.github.io/doc-utils/contributing)
+
+## 💡 Common Workflows
+
+### Clean Up Documentation
+
+```bash
+# 1. Create a branch
+git checkout -b doc-cleanup
+
+# 2. Preview what would change
+format-asciidoc-spacing --dry-run .
+archive-unused-files
+archive-unused-images
+
+# 3. Apply changes
+format-asciidoc-spacing .
+archive-unused-files --archive
+archive-unused-images --archive
+
+# 4. Review and commit
+git diff
+git add -A && git commit -m "Clean up documentation"
+```
+
+### Check Documentation Quality
+
+```bash
+# Check readability
+check-scannability --max-words 30 --max-sentences 5
+
+# Find unused attributes
+find-unused-attributes attributes.adoc
+
+# Save results
+find-unused-attributes attributes.adoc --output unused.txt
+```
+
+## 🔧 Exclusions
+
+All tools support excluding files and directories:
+
+```bash
+# Exclude specific directories
+archive-unused-files --exclude-dir ./temp --exclude-dir ./drafts
+
+# Exclude specific files
+check-scannability --exclude-file ./README.adoc
+
+# Use exclusion list file
+echo "./deprecated/" > .docutils-ignore
+archive-unused-images --exclude-list .docutils-ignore
+```
+
+## 🧪 Development
+
+```bash
+# Install dev dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+python -m pytest tests/ -v
+
+# Run specific test
+python -m pytest tests/test_file_utils.py
+```
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](https://rolfedh.github.io/doc-utils/contributing) for details.
+
+Before submitting PRs:
+- ✅ All tests pass
+- ✅ Code follows PEP 8
+- ✅ Documentation updated
+- ✅ Changelog entry added
+
+## 📊 Project Status
+
+- **Latest Version**: 0.1.6
+- **Python Support**: 3.8+
+- **Test Coverage**: 66+ tests (100% passing)
+- **Dependencies**: Minimal (PyYAML for OpenShift-docs support)
+
+## 🔗 Resources
+
+- [Documentation](https://rolfedh.github.io/doc-utils/)
+- [PyPI Package](https://pypi.org/project/rolfedh-doc-utils/)
+- [Issue Tracker](https://github.com/rolfedh/doc-utils/issues)
+- [Changelog](https://github.com/rolfedh/doc-utils/blob/main/CHANGELOG.md)
+- [License](https://github.com/rolfedh/doc-utils/blob/main/LICENSE)
+
+## 📝 License
+
+This project is licensed under the terms specified in the [LICENSE](https://github.com/rolfedh/doc-utils/blob/main/LICENSE) file.
+
+---
+
+Created by [Rolfe Dlugy-Hegwer](https://github.com/rolfedh) for technical writers everywhere.

{rolfedh_doc_utils-0.1.6.dist-info → rolfedh_doc_utils-0.1.7.dist-info}/RECORD

@@ -2,6 +2,7 @@ archive_unused_files.py,sha256=KMC5a1WL3rZ5owoVnncvfpT1YeMKbVXq9giHvadDgbM,1936
 archive_unused_images.py,sha256=PG2o3haovYckgfhoPhl6KRG_a9czyZuqlLkzkupKTCY,1526
 check_scannability.py,sha256=gcM-vFXKHGP_yFBz7-V5xbXWhIMmtMzBYIGwP9CFbzI,5140
 find_unused_attributes.py,sha256=fk-K32eoCVHxoj7RiBNgSmX1arBLuwYfdSAOMc-wIx0,1677
+format_asciidoc_spacing.py,sha256=Jy_V8c03KGRPJxu4uPdDuMsFg-Q-4AGD9BdkGnApUu8,13241
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
 doc_utils/scannability.py,sha256=XwlmHqDs69p_V36X7DLjPTy0DUoLszSGqYjJ9wE-3hg,982
@@ -9,9 +10,9 @@ doc_utils/topic_map_parser.py,sha256=tKcIO1m9r2K6dvPRGue58zqMr0O2zKU1gnZMzEE3U6o
 doc_utils/unused_adoc.py,sha256=2cbqcYr1os2EhETUU928BlPRlsZVSdI00qaMhqjSIqQ,5263
 doc_utils/unused_attributes.py,sha256=HBgmHelqearfWl3TTC2bZGiJytjLADIgiGQUNKqXXPg,1847
 doc_utils/unused_images.py,sha256=nqn36Bbrmon2KlGlcaruNjJJvTQ8_9H0WU9GvCW7rW8,1456
-rolfedh_doc_utils-0.1.6.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.6.dist-info/METADATA,sha256=JoFOMLPMcQiGaSXBwqXLVZP5jLahLSP0s8_go98X4N8,8787
-rolfedh_doc_utils-0.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rolfedh_doc_utils-0.1.6.dist-info/entry_points.txt,sha256=dA-u4qlxKcewUAOFgaeW1NUIrkhsVknuwFuGTn1-84w,271
-rolfedh_doc_utils-0.1.6.dist-info/top_level.txt,sha256=WrYqTa4wbjRPMUl2hgJBfP734XsXLkhbnzUublx8S0s,119
-rolfedh_doc_utils-0.1.6.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.7.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.7.dist-info/METADATA,sha256=KZ9pa1ZFWS_rj4iVRW9TTbL6RPWvVFfL2twZseuk9Ko,6200
+rolfedh_doc_utils-0.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rolfedh_doc_utils-0.1.7.dist-info/entry_points.txt,sha256=dA-u4qlxKcewUAOFgaeW1NUIrkhsVknuwFuGTn1-84w,271
+rolfedh_doc_utils-0.1.7.dist-info/top_level.txt,sha256=WrYqTa4wbjRPMUl2hgJBfP734XsXLkhbnzUublx8S0s,119
+rolfedh_doc_utils-0.1.7.dist-info/RECORD,,

rolfedh_doc_utils-0.1.6.dist-info/METADATA

@@ -1,303 +0,0 @@
-Metadata-Version: 2.4
-Name: rolfedh-doc-utils
-Version: 0.1.6
-Summary: CLI tools for AsciiDoc documentation projects
-Author: Rolfe Dlugy-Hegwer
-License: MIT License
-        
-        Copyright (c) 2025 Rolfe Dlugy-Hegwer
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: PyYAML>=6.0
-Dynamic: license-file
-
-# doc-utils
-
-A set of Python utilities and CLI tools to help technical writers maintain AsciiDoc documentation repositories.
-
-> ⚠️ **IMPORTANT: Safety First**
->
-> These tools can modify or delete files in your documentation repository. Always:
-> - **Work in a git branch** - Never run these tools on the main/master branch
-> - **Review all changes carefully** - Use `git diff` or a pull request to verify modifications
-> - **Check your preview builds** - Ensure no documentation errors were introduced
-
-## Resources
-
-- [PyPI: rolfedh-doc-utils](https://pypi.org/project/rolfedh-doc-utils/)
-- [GitHub repository](https://github.com/rolfedh/doc-utils)
-
-## Installation
-
-### From PyPI
-
-On modern Linux distributions, you may encounter an "externally-managed-environment" error. Use one of these methods:
-
-**Option 1: pipx (Recommended for CLI tools)**
-```sh
-pipx install rolfedh-doc-utils
-```
-
-**Option 2: pip with --user flag**
-```sh
-pip install --user rolfedh-doc-utils
-```
-
-**Option 3: Traditional pip (may require virtual environment)**
-```sh
-pip install rolfedh-doc-utils
-```
-
-### Upgrading
-
-To upgrade to the latest version:
-
-```sh
-# If installed with pipx:
-pipx upgrade rolfedh-doc-utils
-
-# If installed with pip:
-pip install --upgrade rolfedh-doc-utils  # or --user flag if needed
-```
-
-### For Development
-
-If you're developing or testing locally, install the package in editable mode:
-
-```sh
-# Clone the repository
-git clone https://github.com/rolfedh/doc-utils.git
-cd doc-utils
-
-# Install in editable mode
-pip install -e .
-```
-
-The following CLI tools are installed:
-
-* `check-scannability`
-* `archive-unused-files`
-* `archive-unused-images`
-* `find-unused-attributes`
-* `format-asciidoc-spacing`
-
-These tools can be run from any directory.
-
-### Add to PATH (if needed)
-
-By default, CLI tools install to:
-
-```sh
-$HOME/.local/bin
-```
-
-If this directory isn’t in your `PATH`, commands may not run. Append it to your shell configuration:
-
-```sh
-echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc
-```
-
-Then reload your shell:
-
-```sh
-source ~/.bashrc   # or ~/.zshrc
-```
-
-## CLI Tools Overview
-
-### `check-scannability`
-
-Scans `.adoc` files in the current directory to report:
-
-* Sentences that exceed a length limit (default: 22 words)
-* Paragraphs with too many sentences (default: 3 sentences)
-* Supports exclusion of files and directories
-
-➡️ See [Scannability Checker for AsciiDoc Files](https://github.com/rolfedh/doc-utils/blob/main/check_scannability.md) for details.
-
----
-
-### `archive-unused-files`
-
-Scans the `./modules` and `./assemblies` directories for `.adoc` files that are not referenced. Optionally archives and deletes them.
-
-Works with both:
-- **OpenShift-docs style** repositories (uses `_topic_maps/*.yml` files)
-- **Traditional AsciiDoc** repositories (uses `master.adoc` files)
-
-➡️ See [Archive Unused AsciiDoc Files](https://github.com/rolfedh/doc-utils/blob/main/archive_unused_files.md).
-
----
-
-### `archive-unused-images`
-
-Finds unused image files (e.g., `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`) in the current directory and optionally archives and deletes them.
-
-➡️ See [Archive Unused Images](https://github.com/rolfedh/doc-utils/blob/main/archive_unused_images.md).
-
----
-
-### `find-unused-attributes`
-
-Scans an attributes file (e.g., `attributes.adoc`) for unused attribute definitions across all `.adoc` files in the current directory.
-
-➡️ See [Find Unused AsciiDoc Attributes](https://github.com/rolfedh/doc-utils/blob/main/find_unused_attributes.md).
-
----
-
-### `format-asciidoc-spacing`
-
-Ensures proper spacing in AsciiDoc files by adding blank lines after headings and around `include::` directives.
-
-Formatting rules:
-- Adds blank line after headings (`=`, `==`, `===`, etc.)
-- Adds blank lines before and after `include::` directives
-- Preserves existing spacing where appropriate
-
-Implemented as a Python script (`format-asciidoc-spacing.py`).
-
-➡️ See [AsciiDoc Spacing Formatter](https://github.com/rolfedh/doc-utils/blob/main/format_asciidoc_spacing.md).
-
-## Best Practices for Safe Usage
-
-### Before Running Any Tool:
-
-- **Create a feature branch:**
-   ```sh
-   git checkout -b doc-cleanup-$(date +%Y%m%d)
-   ```
-
-- **Commit any pending changes:**
-   ```sh
-   git add -A && git commit -m "Save work before cleanup"
-   ```
-
-- **Run tools in preview mode first:**
-   - For archive tools: Run without `--archive` to see what would be affected
-
-- **Review all changes and preview builds**
-
-- **Only merge after verification:**
-
-## Usage
-
-To run the tools after installation:
-
-```sh
-check-scannability --help
-archive-unused-files --help
-find-unused-attributes attributes.adoc
-format-asciidoc-spacing --help
-```
-
-Or run them directly from source:
-
-```sh
-python3 check_scannability.py
-python3 archive_unused_files.py
-python3 find_unused_attributes.py attributes.adoc
-python3 format-asciidoc-spacing.py
-```
-
-### Directory/File Exclusion
-
-All tools support excluding specific directories and files from scanning. You can use these options:
-
-1. **`--exclude-dir`** - Exclude specific directories (can be used multiple times):
-   ```sh
-   archive-unused-files --exclude-dir ./modules/temp --exclude-dir ./modules/old
-   ```
-
-2. **`--exclude-file`** - Exclude specific files (can be used multiple times):
-   ```sh
-   check-scannability --exclude-file ./README.adoc --exclude-file ./test.adoc
-   ```
-
-3. **`--exclude-list`** - Point to a text file containing exclusions:
-   ```sh
-   archive-unused-images --exclude-list .docutils-ignore
-   ```
-
-   The exclusion file format:
-   ```
-   # Comments are supported
-   ./modules/deprecated/
-   ./assemblies/archive/
-   ./images/temp/
-   specific-file.adoc
-   ```
-
-**Note:** When you exclude a parent directory, all its subdirectories are automatically excluded. Symbolic links are never followed during scanning.
-
-## Troubleshooting
-
-### ModuleNotFoundError
-
-If you see an error like `ModuleNotFoundError: No module named 'find_unused_attributes'`, this typically means:
-
-1. The package isn't installed. Run:
-   ```sh
-   pipx install rolfedh-doc-utils  # or pip install --user rolfedh-doc-utils
-   ```
-
-2. You're trying to run the script directly without installation. Either:
-   - Install the package first (see Installation section)
-   - Run the script using Python directly:
-     ```sh
-     python3 find_unused_attributes.py attributes.adoc
-     ```
-
-### Command not found
-
-If the command isn't found after installation, ensure `$HOME/.local/bin` is in your PATH (see "Add to PATH" section above).
-
-## Development
-
-### Running Tests
-
-The project includes a comprehensive test suite. To run tests:
-
-```sh
-# Install development dependencies
-pip install -r requirements-dev.txt
-
-# Run all tests
-python -m pytest tests/
-
-# Run with verbose output
-python -m pytest tests/ -v
-```
-
-### Contributing
-
-Contributions are welcome! Please ensure:
-- All tests pass before submitting a PR
-- New features include appropriate tests
-- Code follows PEP 8 style guidelines
-- Documentation is updated as needed
-
-See [Contributing Guidelines](https://github.com/rolfedh/doc-utils/blob/main/CONTRIBUTING.md) for more details.
-
-## License
-
-This project is licensed under the terms of the [LICENSE](https://github.com/rolfedh/doc-utils/blob/main/LICENSE).