rolfedh-doc-utils 0.1.40__py3-none-any.whl → 0.1.42__py3-none-any.whl

callout_lib/converter_deflist.py

@@ -41,41 +41,20 @@ class DefListConverter:
         if table_title:
             # Remove leading dot and trailing period if present
             title_text = table_title.lstrip('.').rstrip('.')
-            lines = [f'\n{title_text}, where:']
+            lines = [f'{title_text}, where:']
         else:
-            lines = ['\nwhere:']
+            lines = ['where:']
 
         # Process each group (which may contain one or more callouts)
         for group in callout_groups:
             code_line = group.code_line
             callout_nums = group.callout_numbers
 
-            # COMMENTED OUT: User-replaceable value detection causes false positives
-            # with Java generics (e.g., <MyEntity, Integer>) and other valid syntax
-            # that uses angle brackets. Always use the full code line as the term.
-            #
-            # # Check if this is a user-replaceable value (contains angle brackets but not heredoc)
-            # # User values are single words/phrases in angle brackets like <my-value>
-            # user_values = DefListConverter.USER_VALUE_PATTERN.findall(code_line)
-            #
-            # if user_values and len(user_values) == 1 and len(code_line) < 100:
-            #     # This looks like a user-replaceable value placeholder
-            #     # Format the value (ensure it has angle brackets)
-            #     user_value = user_values[0]
-            #     if not user_value.startswith('<'):
-            #         user_value = f'<{user_value}>'
-            #     if not user_value.endswith('>'):
-            #         user_value = f'{user_value}>'
-            #     term = f'`{user_value}`'
-            # else:
-            #     # This is a code line - strip whitespace before wrapping in backticks
-            #     term = f'`{code_line.strip()}`'
-
             # Always use the full code line - strip whitespace before wrapping in backticks
             term = f'`{code_line.strip()}`'
 
-            # Add blank line before each term
-            lines.append('')
+            # Add continuation marker before each definition term
+            lines.append('+')
             lines.append(f'{term}::')
 
             # Add explanations for all callouts in this group

callout_lib/detector.py

@@ -281,8 +281,8 @@ class CalloutDetector:
         explanations = {}
         i = start_line + 1  # Start after the closing delimiter
 
-        # Skip blank lines and continuation markers (+)
-        while i < len(lines) and (not lines[i].strip() or lines[i].strip() == '+'):
+        # Skip blank lines, continuation markers (+), and {nbsp} spacers
+        while i < len(lines) and (not lines[i].strip() or lines[i].strip() in ('+', '{nbsp}')):
             i += 1
 
         # Collect consecutive callout explanation lines
@@ -298,8 +298,18 @@ class CalloutDetector:
                 # Continue until we hit a blank line, a new callout, or certain patterns
                 while i < len(lines):
                     line = lines[i]
-                    # Stop if we hit a blank line, new callout, or list start marker
-                    if not line.strip() or self.CALLOUT_EXPLANATION.match(line) or line.startswith('[start='):
+                    stripped = line.strip()
+                    # Stop if we hit:
+                    # - blank line
+                    # - new callout explanation
+                    # - list start marker [start=N]
+                    # - standalone + (list continuation that attaches to parent)
+                    # - admonition block start [NOTE], [IMPORTANT], [WARNING], [TIP], [CAUTION]
+                    if (not stripped or
+                        self.CALLOUT_EXPLANATION.match(line) or
+                        line.startswith('[start=') or
+                        stripped == '+' or
+                        stripped in ('[NOTE]', '[IMPORTANT]', '[WARNING]', '[TIP]', '[CAUTION]')):
                         break
                     # Add continuation line preserving original formatting
                     explanation_lines.append(line)

convert_callouts_interactive.py

@@ -381,10 +381,19 @@ class InteractiveCalloutConverter:
                 )
             else:
                 # Remove old explanations, add new list
+                # Find where explanations actually start (skip {nbsp} and + markers to preserve them)
+                explanation_start_line = block.end_line + 1
+                while explanation_start_line < len(new_lines) and (
+                    not new_lines[explanation_start_line].strip() or
+                    new_lines[explanation_start_line].strip() in ('+', '{nbsp}')
+                ):
+                    explanation_start_line += 1
+
                 new_section = (
                     new_lines[:content_start] +
                     converted_content +
-                    [new_lines[content_end]] +
+                    [new_lines[content_end]] +  # Keep closing delimiter
+                    new_lines[content_end + 1:explanation_start_line] +  # Preserve {nbsp} and + markers
                     output_list +
                     new_lines[explanation_end + 1:]
                 )

convert_callouts_to_deflist.py

@@ -245,9 +245,13 @@ class CalloutConverter:
                     # Table format: preserve content between code block and table start
                     explanation_start_line = self.detector.last_table.start_line
                 else:
-                    # List format: skip blank lines after code block
+                    # List format: skip blank lines, {nbsp} spacers, and + continuation markers
+                    # These will be preserved in the output via the slice below
                     explanation_start_line = block.end_line + 1
-                    while explanation_start_line < len(new_lines) and not new_lines[explanation_start_line].strip():
+                    while explanation_start_line < len(new_lines) and (
+                        not new_lines[explanation_start_line].strip() or
+                        new_lines[explanation_start_line].strip() in ('+', '{nbsp}')
+                    ):
                         explanation_start_line += 1
 
                 # Build the new section

convert_id_attributes_to_ids.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+convert-id-attributes-to-ids - Convert :id: attribute definitions to AsciiDoc [id="..."] anchors.
+
+This script recursively scans a directory for AsciiDoc files and replaces instances of
+`:id: <id_value>` with `[id="<id_value>_{context}"]`.
+
+Optionally, with --clean-up, it also removes related boilerplate lines:
+- // define ID as an attribute
+- // assign ID conditionally, followed by header
+- include::{modules}/common/id.adoc[]
+"""
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+from doc_utils.spinner import Spinner
+
+
+def find_adoc_files(directory: Path) -> list[Path]:
+    """Recursively find all .adoc files in a directory."""
+    adoc_files = []
+    for root, dirs, files in os.walk(directory, followlinks=False):
+        # Skip hidden directories and common non-content directories
+        dirs[:] = [d for d in dirs if not d.startswith('.') and d not in ('node_modules', '__pycache__')]
+        for file in files:
+            if file.endswith('.adoc'):
+                adoc_files.append(Path(root) / file)
+    return adoc_files
+
+
+def convert_id_attributes(content: str, clean_up: bool = False) -> tuple[str, int, int]:
+    """
+    Convert :id: attributes to [id="..._{context}"] format.
+
+    Args:
+        content: The file content to process
+        clean_up: If True, also remove boilerplate lines
+
+    Returns:
+        Tuple of (modified_content, id_replacements_count, cleanup_removals_count)
+    """
+    lines = content.split('\n')
+    new_lines = []
+    id_replacements = 0
+    cleanup_removals = 0
+
+    # Patterns for clean-up (flexible matching for variations)
+    cleanup_patterns = [
+        re.compile(r'^\s*//\s*define ID as an attribute', re.IGNORECASE),
+        re.compile(r'^\s*//\s*assign.*ID conditionally', re.IGNORECASE),
+        re.compile(r'^\s*include::\{modules\}/common/id\.adoc\[\]'),
+    ]
+
+    # Pattern to match :id: <value>
+    id_pattern = re.compile(r'^:id:\s*(.+?)\s*$')
+
+    for line in lines:
+        # Check if this is an :id: line
+        id_match = id_pattern.match(line)
+        if id_match:
+            id_value = id_match.group(1)
+            new_line = f'[id="{id_value}_{{context}}"]'
+            new_lines.append(new_line)
+            id_replacements += 1
+            continue
+
+        # Check if clean-up is enabled and line matches cleanup patterns
+        if clean_up:
+            should_remove = False
+            for pattern in cleanup_patterns:
+                if pattern.search(line):
+                    should_remove = True
+                    cleanup_removals += 1
+                    break
+            if should_remove:
+                continue
+
+        new_lines.append(line)
+
+    return '\n'.join(new_lines), id_replacements, cleanup_removals
+
+
+def process_file(file_path: Path, dry_run: bool = False, clean_up: bool = False) -> tuple[int, int]:
+    """
+    Process a single AsciiDoc file.
+
+    Returns:
+        Tuple of (id_replacements, cleanup_removals)
+    """
+    try:
+        content = file_path.read_text(encoding='utf-8')
+    except Exception as e:
+        print(f"  Error reading {file_path}: {e}")
+        return 0, 0
+
+    new_content, id_replacements, cleanup_removals = convert_id_attributes(content, clean_up)
+
+    if id_replacements > 0 or cleanup_removals > 0:
+        if not dry_run:
+            try:
+                file_path.write_text(new_content, encoding='utf-8')
+            except Exception as e:
+                print(f"  Error writing {file_path}: {e}")
+                return 0, 0
+
+    return id_replacements, cleanup_removals
+
+
+def main():
+    # Check for updates (non-blocking)
+    check_version_on_startup()
+
+    parser = argparse.ArgumentParser(
+        description='Convert :id: attribute definitions to AsciiDoc [id="..._{context}"] anchors.'
+    )
+    parser.add_argument(
+        'directory',
+        nargs='?',
+        default='.',
+        help='Directory to scan for .adoc files (default: current directory)'
+    )
+    parser.add_argument(
+        '--dry-run', '-n',
+        action='store_true',
+        help='Show what would be changed without making actual modifications'
+    )
+    parser.add_argument(
+        '--clean-up',
+        action='store_true',
+        help='Also remove ID-related boilerplate lines (comments and include directives)'
+    )
+    parser.add_argument(
+        '--verbose', '-v',
+        action='store_true',
+        help='Show detailed output for each file processed'
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}'
+    )
+
+    args = parser.parse_args()
+
+    # Resolve directory path
+    directory = Path(args.directory).resolve()
+
+    if not directory.exists():
+        print(f"Error: Directory not found: {directory}")
+        sys.exit(1)
+
+    if not directory.is_dir():
+        print(f"Error: Not a directory: {directory}")
+        sys.exit(1)
+
+    mode_str = "DRY RUN MODE - " if args.dry_run else ""
+    print(f"{mode_str}Scanning directory: {directory}")
+
+    if args.clean_up:
+        print("Clean-up mode enabled: will remove ID-related boilerplate lines")
+
+    # Find all AsciiDoc files
+    spinner = Spinner("Searching for .adoc files")
+    spinner.start()
+    adoc_files = find_adoc_files(directory)
+    spinner.stop(f"Found {len(adoc_files)} .adoc files")
+
+    if not adoc_files:
+        print("No AsciiDoc files found.")
+        sys.exit(0)
+
+    if args.dry_run:
+        print("\n*** DRY RUN MODE - No files will be modified ***\n")
+
+    # Process each file
+    total_id_replacements = 0
+    total_cleanup_removals = 0
+    files_modified = 0
+
+    spinner = Spinner(f"Processing {len(adoc_files)} files")
+    spinner.start()
+
+    for file_path in adoc_files:
+        id_replacements, cleanup_removals = process_file(file_path, args.dry_run, args.clean_up)
+
+        if id_replacements > 0 or cleanup_removals > 0:
+            files_modified += 1
+            total_id_replacements += id_replacements
+            total_cleanup_removals += cleanup_removals
+
+            if args.verbose:
+                rel_path = file_path.relative_to(directory)
+                changes = []
+                if id_replacements > 0:
+                    changes.append(f"{id_replacements} ID conversion(s)")
+                if cleanup_removals > 0:
+                    changes.append(f"{cleanup_removals} line(s) removed")
+                print(f"  {rel_path}: {', '.join(changes)}")
+
+    spinner.stop(f"Processed {len(adoc_files)} files")
+
+    # Summary
+    print(f"\nSummary:")
+    if args.dry_run:
+        print(f"  Files that would be modified: {files_modified}")
+        print(f"  :id: attributes that would be converted: {total_id_replacements}")
+        if args.clean_up:
+            print(f"  Boilerplate lines that would be removed: {total_cleanup_removals}")
+        print("\nRun without --dry-run to apply changes.")
+    else:
+        print(f"  Files modified: {files_modified}")
+        print(f"  :id: attributes converted: {total_id_replacements}")
+        if args.clean_up:
+            print(f"  Boilerplate lines removed: {total_cleanup_removals}")
+
+        if total_id_replacements == 0:
+            print("\nNo :id: attributes found to convert.")
+        else:
+            print("\nConversion complete!")
+
+
+if __name__ == '__main__':
+    main()

doc_utils/insert_abstract_role.py

@@ -0,0 +1,220 @@
+"""
+Insert abstract role - ensures AsciiDoc files have [role="_abstract"] above the first paragraph.
+
+Core logic for adding the [role="_abstract"] attribute required for DITA short description conversion.
+"""
+
+import re
+from pathlib import Path
+from typing import List, Tuple, Optional
+
+
+def find_first_paragraph_after_title(lines: List[str]) -> Optional[int]:
+    """
+    Find the line index of the first paragraph after the document title.
+
+    The first paragraph is the first non-empty line that:
+    - Comes after a level 1 heading (= Title)
+    - Is not an attribute definition (starts with :)
+    - Is not a comment (starts with //)
+    - Is not a block attribute (starts with [)
+    - Is not another heading
+
+    Args:
+        lines: List of lines from the file (without trailing newlines)
+
+    Returns:
+        Line index of the first paragraph, or None if not found
+    """
+    title_found = False
+    title_index = -1
+
+    for i, line in enumerate(lines):
+        # Check for level 1 heading (document title)
+        if re.match(r'^=\s+[^=]', line):
+            title_found = True
+            title_index = i
+            continue
+
+        # Only look for first paragraph after we've found the title
+        if not title_found:
+            continue
+
+        # Skip empty lines
+        if re.match(r'^\s*$', line):
+            continue
+
+        # Skip attribute definitions
+        if re.match(r'^:', line):
+            continue
+
+        # Skip comments (single line)
+        if re.match(r'^//', line):
+            continue
+
+        # Skip block attributes like [role=...], [id=...], etc.
+        if re.match(r'^\[', line):
+            continue
+
+        # Skip other headings
+        if re.match(r'^=+\s+', line):
+            continue
+
+        # Skip include directives
+        if re.match(r'^include::', line):
+            continue
+
+        # This is the first paragraph
+        return i
+
+    return None
+
+
+def has_abstract_role(lines: List[str], paragraph_index: int) -> bool:
+    """
+    Check if there's already a [role="_abstract"] before the paragraph.
+
+    Args:
+        lines: List of lines from the file
+        paragraph_index: Index of the first paragraph
+
+    Returns:
+        True if [role="_abstract"] already exists before the paragraph
+    """
+    # Look at the lines immediately before the paragraph
+    for i in range(paragraph_index - 1, -1, -1):
+        line = lines[i].strip()
+
+        # Skip empty lines
+        if not line:
+            continue
+
+        # Found abstract role
+        if re.match(r'^\[role=["\']_abstract["\']\]$', line):
+            return True
+
+        # If we hit any other non-empty content, stop looking
+        # (could be attribute, heading, etc.)
+        break
+
+    return False
+
+
+def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> Tuple[bool, List[str]]:
+    """
+    Process a single AsciiDoc file to add [role="_abstract"] if needed.
+
+    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:
+        Tuple of (changes_made, messages) where messages is a list of verbose output
+    """
+    messages = []
+
+    if verbose:
+        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:
+        raise IOError(f"Error reading {file_path}: {e}")
+
+    # Remove trailing newlines from lines for processing
+    lines = [line.rstrip('\n\r') for line in lines]
+
+    # Find the first paragraph after the title
+    paragraph_index = find_first_paragraph_after_title(lines)
+
+    if paragraph_index is None:
+        if verbose:
+            messages.append("  No paragraph found after title")
+        return False, messages
+
+    # Check if abstract role already exists
+    if has_abstract_role(lines, paragraph_index):
+        if verbose:
+            messages.append("  [role=\"_abstract\"] already present")
+        return False, messages
+
+    # Insert [role="_abstract"] before the first paragraph
+    # We need to add it with a blank line before it if there isn't one
+    new_lines = lines[:paragraph_index]
+
+    # Check if we need to add a blank line before the role
+    if paragraph_index > 0 and lines[paragraph_index - 1].strip():
+        new_lines.append('')
+
+    new_lines.append('[role="_abstract"]')
+    new_lines.extend(lines[paragraph_index:])
+
+    if verbose:
+        preview = lines[paragraph_index][:60] + "..." if len(lines[paragraph_index]) > 60 else lines[paragraph_index]
+        messages.append(f"  Adding [role=\"_abstract\"] before line {paragraph_index + 1}: {preview}")
+
+    if not dry_run:
+        try:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                for line in new_lines:
+                    f.write(line + '\n')
+        except IOError as e:
+            raise IOError(f"Error writing {file_path}: {e}")
+
+    return True, messages
+
+
+def find_adoc_files(path: Path, exclude_dirs: List[str] = None, exclude_files: List[str] = None) -> List[Path]:
+    """
+    Find all .adoc files in the given path.
+
+    Args:
+        path: File or directory path to search
+        exclude_dirs: List of directory paths to exclude
+        exclude_files: List of file paths to exclude
+
+    Returns:
+        List of Path objects for .adoc files
+    """
+    exclude_dirs = exclude_dirs or []
+    exclude_files = exclude_files or []
+
+    # Normalize exclusion paths to absolute
+    exclude_dirs_abs = [Path(d).resolve() for d in exclude_dirs]
+    exclude_files_abs = [Path(f).resolve() for f in exclude_files]
+
+    adoc_files = []
+
+    if path.is_file():
+        if path.suffix == '.adoc':
+            path_abs = path.resolve()
+            if path_abs not in exclude_files_abs:
+                adoc_files.append(path)
+    elif path.is_dir():
+        for adoc_path in path.rglob('*.adoc'):
+            # Skip symlinks
+            if adoc_path.is_symlink():
+                continue
+
+            path_abs = adoc_path.resolve()
+
+            # Check if file is excluded
+            if path_abs in exclude_files_abs:
+                continue
+
+            # Check if any parent directory is excluded
+            skip = False
+            for exclude_dir in exclude_dirs_abs:
+                try:
+                    path_abs.relative_to(exclude_dir)
+                    skip = True
+                    break
+                except ValueError:
+                    pass
+
+            if not skip:
+                adoc_files.append(adoc_path)
+
+    return sorted(adoc_files)

doc_utils/version.py

@@ -1,7 +1,7 @@
 """Version information for doc-utils."""
 
 # This should match the version in pyproject.toml
-__version__ = "0.1.40"
+__version__ = "0.1.42"
 
 def get_version():
     """Return the current version string."""

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()

insert_procedure_title.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""
+Insert .Procedure block title above numbered steps in AsciiDoc procedure files.
+
+This script finds AsciiDoc procedure files (those with :_mod-docs-content-type: PROCEDURE)
+and inserts a .Procedure block title before the first numbered step if one is missing.
+
+Usage:
+    insert-procedure-title <file_or_directory> [options]
+
+Examples:
+    insert-procedure-title modules/proc_example.adoc
+    insert-procedure-title modules/ --dry-run
+    insert-procedure-title . --verbose
+"""
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def is_procedure_file(content: str) -> bool:
+    """Check if file is a PROCEDURE content type."""
+    return ':_mod-docs-content-type: PROCEDURE' in content
+
+
+def find_first_numbered_step(lines: list[str]) -> int | None:
+    """
+    Find the line index of the first numbered step.
+
+    Numbered steps can be:
+    - `. Step text` (AsciiDoc implicit ordered list)
+    - `1. Step text` (explicit numbered list)
+
+    Returns None if no numbered steps found.
+    """
+    # Pattern for ordered list items:
+    # - Starts with `. ` (implicit) or `<digit>. ` (explicit)
+    # - Must not be a block title (block titles are `.Title` without space after dot)
+    ordered_list_pattern = re.compile(r'^(\d+\.\s|\.(?!\w)\s)')
+
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if ordered_list_pattern.match(stripped):
+            return i
+    return None
+
+
+def has_procedure_title_before(lines: list[str], step_index: int) -> bool:
+    """
+    Check if there's a .Procedure block title before the numbered steps.
+
+    Looks backward from the step index to find `.Procedure` on its own line.
+    Continues past other block titles (like sub-section titles) until hitting
+    a section heading (= or ==) or the start of the file.
+    """
+    for i in range(step_index - 1, -1, -1):
+        stripped = lines[i].strip()
+        if stripped == '.Procedure':
+            return True
+        # Stop searching if we hit a section heading
+        if stripped.startswith('= ') or stripped.startswith('== '):
+            return False
+    return False
+
+
+def find_insertion_point(lines: list[str], step_index: int) -> int:
+    """
+    Find the correct line index to insert .Procedure block title.
+
+    The insertion point should be before the numbered steps, but after:
+    - Prerequisites block
+    - Introductory paragraphs
+    - Blank lines
+
+    Returns the line index where .Procedure should be inserted.
+    """
+    # Look backward from the step to find a good insertion point
+    # We want to insert just before the numbered list starts
+    insertion_point = step_index
+
+    # Skip backward over any preceding blank lines to insert before them
+    while insertion_point > 0 and lines[insertion_point - 1].strip() == '':
+        insertion_point -= 1
+
+    return insertion_point
+
+
+def insert_procedure_title(content: str) -> tuple[str, bool]:
+    """
+    Insert .Procedure block title if missing.
+
+    Returns:
+        tuple: (modified_content, was_modified)
+    """
+    lines = content.split('\n')
+
+    # Find the first numbered step
+    step_index = find_first_numbered_step(lines)
+    if step_index is None:
+        return content, False
+
+    # Check if .Procedure already exists before the steps
+    if has_procedure_title_before(lines, step_index):
+        return content, False
+
+    # Find where to insert
+    insertion_point = find_insertion_point(lines, step_index)
+
+    # Insert .Procedure followed by blank line
+    # If there's already a blank line before steps, just insert .Procedure
+    if insertion_point < len(lines) and lines[insertion_point].strip() == '':
+        lines.insert(insertion_point, '.Procedure')
+        lines.insert(insertion_point + 1, '')
+    else:
+        lines.insert(insertion_point, '')
+        lines.insert(insertion_point, '.Procedure')
+
+    return '\n'.join(lines), True
+
+
+def has_numbered_steps(content: str) -> bool:
+    """Check if file has numbered steps."""
+    lines = content.split('\n')
+    return find_first_numbered_step(lines) is not None
+
+
+def has_procedure_title(content: str) -> bool:
+    """Check if file has a .Procedure block title."""
+    for line in content.split('\n'):
+        if line.strip() == '.Procedure':
+            return True
+    return False
+
+
+def process_file(filepath: Path, dry_run: bool = False, verbose: bool = False) -> tuple[bool, bool]:
+    """
+    Process a single AsciiDoc file.
+
+    Returns tuple: (was_modified, has_warning)
+    """
+    try:
+        content = filepath.read_text(encoding='utf-8')
+    except Exception as e:
+        print(f"Error reading {filepath}: {e}", file=sys.stderr)
+        return False, False
+
+    # Only process PROCEDURE files
+    if not is_procedure_file(content):
+        if verbose:
+            print(f"Skipping (not a procedure file): {filepath}")
+        return False, False
+
+    # If file already has .Procedure, no action needed
+    # (handles cases where procedures use unordered lists instead of numbered steps)
+    if has_procedure_title(content):
+        if verbose:
+            print(f"No changes needed (has .Procedure): {filepath}")
+        return False, False
+
+    # Check if file has numbered steps
+    if not has_numbered_steps(content):
+        print(f"Warning: Procedure file has no numbered steps and no .Procedure title: {filepath}")
+        return False, True
+
+    new_content, was_modified = insert_procedure_title(content)
+
+    if was_modified:
+        if dry_run:
+            print(f"Would modify: {filepath}")
+        else:
+            filepath.write_text(new_content, encoding='utf-8')
+            print(f"Modified: {filepath}")
+        return True, False
+    else:
+        if verbose:
+            print(f"No changes needed: {filepath}")
+        return False, False
+
+
+def collect_adoc_files(path: Path) -> list[Path]:
+    """Collect all .adoc files from path (file or directory)."""
+    if path.is_file():
+        if path.suffix == '.adoc':
+            return [path]
+        return []
+
+    files = []
+    for root, _, filenames in os.walk(path):
+        for filename in filenames:
+            if filename.endswith('.adoc'):
+                files.append(Path(root) / filename)
+    return sorted(files)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Insert .Procedure block title above numbered steps in AsciiDoc procedure files.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  %(prog)s modules/proc_example.adoc
+  %(prog)s modules/ --dry-run
+  %(prog)s . --verbose
+        '''
+    )
+    parser.add_argument(
+        'path',
+        type=Path,
+        help='File or directory to process'
+    )
+    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 all files processed, including those not modified'
+    )
+
+    args = parser.parse_args()
+
+    if not args.path.exists():
+        print(f"Error: Path does not exist: {args.path}", file=sys.stderr)
+        sys.exit(1)
+
+    files = collect_adoc_files(args.path)
+
+    if not files:
+        print(f"No .adoc files found in: {args.path}")
+        sys.exit(0)
+
+    modified_count = 0
+    warning_count = 0
+    for filepath in files:
+        was_modified, has_warning = process_file(filepath, dry_run=args.dry_run, verbose=args.verbose)
+        if was_modified:
+            modified_count += 1
+        if has_warning:
+            warning_count += 1
+
+    print()
+    if args.dry_run:
+        print(f"Dry run complete. {modified_count} file(s) would be modified.")
+    else:
+        print(f"Complete. {modified_count} file(s) modified.")
+
+    if warning_count > 0:
+        print(f"Warnings: {warning_count} procedure file(s) have no numbered steps.")
+
+
+if __name__ == '__main__':
+    main()

{rolfedh_doc_utils-0.1.40.dist-info → rolfedh_doc_utils-0.1.42.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.40
+Version: 0.1.42
 Summary: CLI tools for AsciiDoc documentation projects
 Author: Rolfe Dlugy-Hegwer
 License: MIT License

{rolfedh_doc_utils-0.1.40.dist-info → rolfedh_doc_utils-0.1.42.dist-info}/RECORD

@@ -3,9 +3,10 @@ archive_unused_images.py,sha256=EvPhMIwp6_AHKtuNYQ663q6biXBeXaqf88NzWrhvtIE,2029
 check_published_links.py,sha256=nk07prV6xHVqVrYCy2Eb8BWkjkgJBhczk8U0E-KeIvA,43258
 check_scannability.py,sha256=O6ROr-e624jVPvPpASpsWo0gTfuCFpA2mTSX61BjAEI,5478
 check_source_directives.py,sha256=JiIvn_ph9VKPMH4zg-aSsuIGQZcnI_imj7rZLLE04L8,3660
-convert_callouts_interactive.py,sha256=4PjiVIOWxNJiJLQuBHT3x6rE46-hgfFHSaoo5quYIs8,22889
-convert_callouts_to_deflist.py,sha256=BoqW5_GkQ-KqNzn4vmE6lsQosrPV0lkB-bfAx3dzyMw,25886
+convert_callouts_interactive.py,sha256=VJo3CePMr13NJXTHkuZ1lSiSSasfKlV08Bw8tHBzyuI,23468
+convert_callouts_to_deflist.py,sha256=fHr7RYq1ZjVvX221CYenf5E52RadDhph8DQfZ1YLLHw,26129
 convert_freemarker_to_asciidoc.py,sha256=ki0bFDPWxl9aUHK_-xqffIKF4KJYMXA8S4XLG_mOA0U,10097
+convert_id_attributes_to_ids.py,sha256=bqeKapxCCzonLxSJ-5W-fZacnAm0yyZrukoqKVFHU8Y,7407
 convert_tables_to_deflists.py,sha256=PIP6xummuMqC3aSzahKKRBYahes_j5ZpHp_-k6BjurY,15599
 doc_utils_cli.py,sha256=J3CE7cTDDCRGkhAknYejNWHhk5t9YFGt27WDVfR98Xk,5111
 extract_link_attributes.py,sha256=wR2SmR2la-jR6DzDbas2PoNONgRZ4dZ6aqwzkwEv8Gs,3516
@@ -13,14 +14,16 @@ find_duplicate_content.py,sha256=iYWekmriItXWSd8nBnIQN_FoZkv6quPJNL0qjv6UxUA,634
 find_duplicate_includes.py,sha256=sQaVLOe4Ksc3t08_A_2GaLMwQCgKe9Nsr8c3ipp1Ph0,5456
 find_unused_attributes.py,sha256=AQVJsvRRgGsDjOZClcvJRQ5i5H2YrClcR-1nRLVBzI8,5140
 format_asciidoc_spacing.py,sha256=nmWpw2dgwhd81LXyznq0rT8w6Z7cNRyGtPJGRyKFRdc,4212
+insert_abstract_role.py,sha256=C1PZilpYTC1xUfdujAarNXo3oYXbToLdQB4wCpWQrsg,5454
+insert_procedure_title.py,sha256=MnhSG2_e5v7v3XXU4NXr2vjk6BuppVNalCoUMuBupjI,7917
 inventory_conditionals.py,sha256=vLWEDTj9MbqUnA_iw4g-HEVX47fSG8tfd4KpSJKg6kA,1416
 replace_link_attributes.py,sha256=Cpc4E-j9j-4_y0LOstAKYOPl02Ln_2bGNIeqp3ZVCdA,7624
 validate_links.py,sha256=lWuK8sgfiFdfcUdSVAt_5U9JHVde_oa6peSUlBQtsac,6145
 callout_lib/__init__.py,sha256=8B82N_z4D1LaZVYgd5jZR53QAabtgPzADOyGlnvihj0,665
 callout_lib/converter_bullets.py,sha256=nfH0hz4p8qNM2F-MhtBjwH-lUYcNf2m1sdJebRlCxoo,4405
 callout_lib/converter_comments.py,sha256=do0dH8uOyNFpn5CDEzR0jYYCMIPP3oPFM8cEB-Fp22c,9767
-callout_lib/converter_deflist.py,sha256=Ocr3gutTo_Sl_MkzethZH1UO6mCDEcuExGMZF5MfZFg,6131
-callout_lib/detector.py,sha256=S0vZDa4zhTSn6Kv0hWfG56W-5srGxUc-nvpLe_gIx-A,15971
+callout_lib/converter_deflist.py,sha256=Deep2QXqEmJY4Q8cTWyrCpErQdIl7yBnLkibZDlG4EM,4919
+callout_lib/detector.py,sha256=lLg0CuSLIIMHRHuo_3_fLP347pki31sQHoiBpbqRmzo,16498
 callout_lib/table_parser.py,sha256=ZucisADE8RDAk5HtIrttaPgBi6Hf8ZUpw7KzfbcmEjc,31450
 doc_utils/__init__.py,sha256=qqZR3lohzkP63soymrEZPBGzzk6-nFzi4_tSffjmu_0,74
 doc_utils/convert_freemarker_to_asciidoc.py,sha256=UGQ7iS_9bkVdDMAWBORXbK0Q5mLPmDs1cDJqoR4LLH8,22491
@@ -29,6 +32,7 @@ doc_utils/duplicate_includes.py,sha256=8hpL7fq_pHcKMS0C50LTwTyzqth39nMQ9Lz67gie8
 doc_utils/extract_link_attributes.py,sha256=U0EvPZReJQigNfbT-icBsVT6Li64hYki5W7MQz6qqbc,22743
 doc_utils/file_utils.py,sha256=fpTh3xx759sF8sNocdn_arsP3KAv8XA6cTQTAVIZiZg,4247
 doc_utils/format_asciidoc_spacing.py,sha256=RL2WU_dG_UfGL01LnevcyJfKsvYy_ogNyeoVX-Fyqks,13579
+doc_utils/insert_abstract_role.py,sha256=z_Pm8A3EE03DU2fBReJDwMfIUT1qRbDcOKw4EI63I90,6641
 doc_utils/inventory_conditionals.py,sha256=PSrdmeBHbpayvXgaRryqvjUlLZYryPgU9js8IBYqB7g,5486
 doc_utils/missing_source_directive.py,sha256=X3Acn0QJTk6XjmBXhGus5JAjlIitCiicCRE3fslifyw,8048
 doc_utils/replace_link_attributes.py,sha256=gmAs68_njBqEz-Qni-UGgeYEDTMxlTWk_IOm76FONNE,7279
@@ -39,12 +43,12 @@ doc_utils/unused_adoc.py,sha256=LPQWPGEOizXECxepk7E_5cjTVvKn6RXQYTWG97Ps5VQ,9077
 doc_utils/unused_attributes.py,sha256=2UmqdXd5ogaPtj9_teApM0IlkdCmzBZNRh7XXrVYJOk,9032
 doc_utils/unused_images.py,sha256=hL8Qrik9QCkVh54eBLuNczRS9tMnsqIEfavNamM1UeQ,5664
 doc_utils/validate_links.py,sha256=iBGXnwdeLlgIT3fo3v01ApT5k0X2FtctsvkrE6E3VMk,19610
-doc_utils/version.py,sha256=SpBhN4XHbHDf1DgElG_ucDzHppRDj0mgi0TKjJ9LZcA,203
+doc_utils/version.py,sha256=9kAm8RDU9obPgPJ99XR9NylVS9V7v-_6YogFp0RiSNs,203
 doc_utils/version_check.py,sha256=-31Y6AN0KGi_CUCAVOOhf6bPO3r7SQIXPxxeffLAF0w,7535
 doc_utils/warnings_report.py,sha256=20yfwqBjOprfFhQwCujbcsvjJCbHHhmH84uAujm-y-o,8877
-rolfedh_doc_utils-0.1.40.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
-rolfedh_doc_utils-0.1.40.dist-info/METADATA,sha256=ihbfWFiiKMkKJIIQiAshaIF2pvUICaSd3dTSnatqiKo,8654
-rolfedh_doc_utils-0.1.40.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-rolfedh_doc_utils-0.1.40.dist-info/entry_points.txt,sha256=IQlgrL_EV-sqMJyhFGJnVO6F2Ofk9dIxrUmsM8Gwfzk,974
-rolfedh_doc_utils-0.1.40.dist-info/top_level.txt,sha256=T9C7VhOScdaqnOl4OASCar9Nh2EUnPmimj50sMY0LyA,439
-rolfedh_doc_utils-0.1.40.dist-info/RECORD,,
+rolfedh_doc_utils-0.1.42.dist-info/licenses/LICENSE,sha256=vLxtwMVOJA_hEy8b77niTkdmQI9kNJskXHq0dBS36e0,1075
+rolfedh_doc_utils-0.1.42.dist-info/METADATA,sha256=qptswU3wJNmGolK1JTaJUVrvue2NOv3pShN2qN0cOoM,8654
+rolfedh_doc_utils-0.1.42.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+rolfedh_doc_utils-0.1.42.dist-info/entry_points.txt,sha256=3CiBc2vWwHezC6aBBBz9oY0Z6J8ADrFz1B3hh71Lg0o,1141
+rolfedh_doc_utils-0.1.42.dist-info/top_level.txt,sha256=iaqMjXiZZTvQ0wUEL3tHOf48pB-VJw7lw0_20FJ8y64,512
+rolfedh_doc_utils-0.1.42.dist-info/RECORD,,

{rolfedh_doc_utils-0.1.40.dist-info → rolfedh_doc_utils-0.1.42.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{rolfedh_doc_utils-0.1.40.dist-info → rolfedh_doc_utils-0.1.42.dist-info}/entry_points.txt

@@ -7,6 +7,7 @@ check-source-directives = check_source_directives:main
 convert-callouts-interactive = convert_callouts_interactive:main
 convert-callouts-to-deflist = convert_callouts_to_deflist:main
 convert-freemarker-to-asciidoc = convert_freemarker_to_asciidoc:main
+convert-id-attributes-to-ids = convert_id_attributes_to_ids:main
 convert-tables-to-deflists = convert_tables_to_deflists:main
 doc-utils = doc_utils_cli:main
 extract-link-attributes = extract_link_attributes:main
@@ -14,6 +15,8 @@ find-duplicate-content = find_duplicate_content:main
 find-duplicate-includes = find_duplicate_includes:main
 find-unused-attributes = find_unused_attributes:main
 format-asciidoc-spacing = format_asciidoc_spacing:main
+insert-abstract-role = insert_abstract_role:main
+insert-procedure-title = insert_procedure_title:main
 inventory-conditionals = inventory_conditionals:main
 replace-link-attributes = replace_link_attributes:main
 validate-links = validate_links:main

{rolfedh_doc_utils-0.1.40.dist-info → rolfedh_doc_utils-0.1.42.dist-info}/top_level.txt

@@ -7,6 +7,7 @@ check_source_directives
 convert_callouts_interactive
 convert_callouts_to_deflist
 convert_freemarker_to_asciidoc
+convert_id_attributes_to_ids
 convert_tables_to_deflists
 doc_utils
 doc_utils_cli
@@ -15,6 +16,8 @@ find_duplicate_content
 find_duplicate_includes
 find_unused_attributes
 format_asciidoc_spacing
+insert_abstract_role
+insert_procedure_title
 inventory_conditionals
 replace_link_attributes
 validate_links