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

format_asciidoc_spacing.py

@@ -0,0 +1,134 @@
+#!/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
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+
+
+from doc_utils.spinner import Spinner
+# 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():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
+    """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'
+    )
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+    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()

insert_abstract_role.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+insert-abstract-role - Insert [role="_abstract"] above the first paragraph after the title.
+
+Ensures AsciiDoc files have the [role="_abstract"] attribute required for DITA short description
+conversion, as enforced by the AsciiDocDITA.ShortDescription vale rule.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from doc_utils.insert_abstract_role import process_file, find_adoc_files
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+from doc_utils.file_utils import parse_exclude_list_file
+
+
+# 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():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
+
+    parser = argparse.ArgumentParser(
+        description="Insert [role=\"_abstract\"] above the first paragraph after the document title",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Insert [role="_abstract"] above the first paragraph after the document title in AsciiDoc files.
+This attribute is required for DITA short description conversion.
+
+The tool identifies the first paragraph after a level 1 heading (= Title) and inserts
+the [role="_abstract"] attribute on the line immediately before it.
+
+Examples:
+  %(prog)s                                    # Process all .adoc files in current directory
+  %(prog)s modules/                           # Process all .adoc files in modules/
+  %(prog)s modules/rn/my-release-note.adoc    # Process single file
+  %(prog)s --dry-run modules/                 # Preview changes without modifying
+  %(prog)s --exclude-dir .archive modules/    # Exclude .archive directories
+        """
+    )
+
+    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'
+    )
+    parser.add_argument(
+        '--exclude-dir',
+        action='append',
+        default=[],
+        help='Directory to exclude (can be specified multiple times)'
+    )
+    parser.add_argument(
+        '--exclude-file',
+        action='append',
+        default=[],
+        help='File to exclude (can be specified multiple times)'
+    )
+    parser.add_argument(
+        '--exclude-list',
+        help='Path to file containing list of files/directories to exclude (one per line)'
+    )
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+    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)
+
+    # Parse exclusion list file if provided
+    exclude_dirs = list(args.exclude_dir)
+    exclude_files = list(args.exclude_file)
+
+    if args.exclude_list:
+        list_dirs, list_files = parse_exclude_list_file(args.exclude_list)
+        exclude_dirs.extend(list_dirs)
+        exclude_files.extend(list_files)
+
+    # 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, exclude_dirs, exclude_files)
+
+    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("Insert abstract role 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("Insert abstract role complete!")
+
+
+if __name__ == "__main__":
+    main()

inventory_conditionals.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""
+CLI tool to create an inventory of AsciiDoc conditional directives.
+
+Scans .adoc files for ifdef, ifndef, endif, and ifeval directives
+and creates a timestamped inventory file.
+
+Usage:
+    inventory-conditionals [directory] [-o OUTPUT_DIR]
+
+If no directory is specified, the current working directory is used.
+"""
+
+import argparse
+from pathlib import Path
+
+from doc_utils.inventory_conditionals import create_inventory
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Create an inventory of AsciiDoc conditional directives.'
+    )
+    parser.add_argument(
+        'directory',
+        nargs='?',
+        default='.',
+        help='Directory to scan for .adoc files (default: current directory)'
+    )
+    parser.add_argument(
+        '-o', '--output-dir',
+        default=None,
+        help='Directory to write the inventory file (default: current directory)'
+    )
+
+    args = parser.parse_args()
+
+    directory = Path(args.directory).resolve()
+    if not directory.is_dir():
+        print(f"Error: {directory} is not a valid directory")
+        return 1
+
+    output_dir = Path(args.output_dir).resolve() if args.output_dir else Path.cwd()
+
+    print(f"Scanning for .adoc files in: {directory}")
+    output_file = create_inventory(directory, output_dir)
+    print(f"Inventory written to: {output_file}")
+
+    return 0
+
+
+if __name__ == '__main__':
+    exit(main())

replace_link_attributes.py

@@ -0,0 +1,214 @@
+#!/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
+)
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+from doc_utils.spinner import Spinner
+
+
+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():
+    # Check for updates (non-blocking, won't interfere with tool operation)
+    check_version_on_startup()
+    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)'
+    )
+    parser.add_argument(
+        '--macro-type',
+        choices=['link', 'xref', 'both'],
+        default='both',
+        help='Type of macros to process: link, xref, or both (default: both)'
+    )
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+    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:
+        spinner = Spinner("Searching for attributes.adoc files")
+        spinner.start()
+        attributes_files = find_attributes_files(repo_root)
+        spinner.stop()
+        attributes_file = prompt_for_attributes_file(attributes_files)
+
+        if not attributes_file:
+            print("Operation cancelled.")
+            sys.exit(0)
+
+    spinner = Spinner(f"Loading attributes from {attributes_file.name}")
+    spinner.start()
+    attributes = load_attributes(attributes_file)
+
+    if not attributes:
+        spinner.stop("No attributes found in the file", success=False)
+        sys.exit(1)
+
+    # Resolve nested references
+    attributes = resolve_nested_attributes(attributes)
+    spinner.stop(f"Loaded and resolved {len(attributes)} attributes")
+
+    # Find all AsciiDoc files
+    spinner = Spinner(f"Searching for .adoc files in {repo_root}")
+    spinner.start()
+    adoc_files = find_adoc_files(repo_root)
+    spinner.stop()
+
+    # Find ALL attributes files to exclude from processing
+    all_attribute_files = find_attributes_files(repo_root)
+    exclude_paths = {f.resolve() for f in all_attribute_files}
+
+    # Notify user about excluded files if there are multiple
+    if len(all_attribute_files) > 1:
+        print(f"Excluding {len(all_attribute_files)} attributes files from processing:")
+        for f in all_attribute_files:
+            print(f"  - {f.relative_to(repo_root)}")
+
+    # Exclude ALL attributes files, not just the selected one
+    adoc_files = [f for f in adoc_files if f.resolve() not in exclude_paths]
+
+    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
+
+    spinner = Spinner(f"Processing {len(adoc_files)} files")
+    spinner.start()
+
+    for file_path in adoc_files:
+        replacements = replace_link_attributes_in_file(file_path, attributes, args.dry_run, args.macro_type)
+        if replacements > 0:
+            rel_path = file_path.relative_to(repo_root)
+            total_replacements += replacements
+            files_modified += 1
+
+    spinner.stop(f"Processed {len(adoc_files)} files")
+
+    # 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()