rolfedh-doc-utils 0.1.40__tar.gz → 0.1.42__tar.gz

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.42}/PKG-INFO

@@ -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 → rolfedh_doc_utils-0.1.42}/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

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.42}/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)

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.42}/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:]
                 )

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.42}/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

rolfedh_doc_utils-0.1.42/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()

rolfedh_doc_utils-0.1.42/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)

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.42}/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."""