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

doc_utils/format_asciidoc_spacing.py

@@ -0,0 +1,285 @@
+"""
+Format AsciiDoc spacing - ensures blank lines after headings and around include directives.
+
+Core logic for formatting AsciiDoc files with proper spacing.
+"""
+
+import re
+from pathlib import Path
+from typing import List, Tuple
+
+
+def process_file(file_path: Path, dry_run: bool = False, verbose: bool = False) -> Tuple[bool, List[str]]:
+    """
+    Process a single AsciiDoc file to fix spacing issues.
+
+    Args:
+        file_path: Path to the file to process
+        dry_run: If True, show what would be changed without modifying
+        verbose: If True, show detailed output
+
+    Returns:
+        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]
+
+    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
+    in_comment_block = False  # Track if we're inside a //// comment 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
+            # Don't add if previous line is a comment (they form a logical unit)
+            if (prev_line and
+                not re.match(r'^\s*$', prev_line) and
+                not re.match(r'^(ifdef::|ifndef::|endif::)', prev_line) and
+                not re.match(r'^//', prev_line)):
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    messages.append("  Added blank line before conditional block")
+            new_lines.append(current_line)
+
+        # Check for conditional end (endif::)
+        elif re.match(r'^endif::', current_line):
+            new_lines.append(current_line)
+            in_conditional = False
+            # Add blank line after conditional if needed
+            # Don't add if next line is:
+            # - a list item (starts with *, -, ., .., or numbered)
+            # - list continuation (+)
+            # - another conditional
+            # - blank
+            if (next_line and
+                not re.match(r'^\s*$', next_line) and
+                not re.match(r'^(ifdef::|ifndef::|endif::)', next_line) and
+                not re.match(r'^(\*|\-|\.|\.\.|\d+\.)\s', next_line) and  # List items
+                not re.match(r'^\+\s*$', next_line)):  # List continuation
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    messages.append("  Added blank line after conditional block")
+
+        # Check for comment block delimiters (////)
+        elif re.match(r'^////+$', current_line):
+            in_comment_block = not in_comment_block  # Toggle comment block state
+            new_lines.append(current_line)
+
+            # If we're closing a comment block, add blank line after if needed
+            if not in_comment_block:
+                if (next_line and
+                    not re.match(r'^\s*$', next_line) and
+                    not re.match(r'^////+$', next_line)):
+                    new_lines.append("")
+                    changes_made = True
+                    if verbose:
+                        messages.append("  Added blank line after comment 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 for role blocks ([role="..."])
+        # Role blocks don't need special spacing - they're followed directly by content
+        elif not in_block and not in_comment_block and re.match(r'^\[role=', current_line):
+            new_lines.append(current_line)
+
+        # Check for block titles (.Title)
+        elif not in_block and not in_comment_block and re.match(r'^\.[A-Z]', current_line):
+            # Add blank line before block title if needed
+            # Don't add if inside a conditional block or if previous line is a conditional directive
+            if (not in_conditional and
+                prev_line and
+                not re.match(r'^\s*$', prev_line) and
+                not re.match(r'^=+\s+', prev_line) and
+                not re.match(r'^\[role=', prev_line) and
+                not re.match(r'^(ifdef::|ifndef::|endif::)', prev_line)):  # Don't add if previous is conditional
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                    messages.append(f"  Added blank line before block title: {truncated}")
+            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, not another heading, not a comment block, and not a conditional
+            if (next_line and
+                not re.match(r'^=+\s+', next_line) and
+                not re.match(r'^\s*$', next_line) and
+                not re.match(r'^////+$', next_line) and  # Don't add if next is comment block
+                not re.match(r'^(ifdef::|ifndef::|endif::)', next_line)):  # Don't add if next is conditional
+                new_lines.append("")
+                changes_made = True
+                if verbose:
+                    truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                    messages.append(f"  Added blank line after heading: {truncated}")
+
+        # Check if current line is a comment (AsciiDoc comments start with //)
+        elif re.match(r'^//', current_line):
+            # Skip special handling if we're inside a conditional block
+            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
+                    # This includes when previous line is an include (to separate include blocks)
+                    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)):
+                        new_lines.append("")
+                        changes_made = True
+                        if verbose:
+                            messages.append("  Added blank line before comment above include")
+                    new_lines.append(current_line)
+                else:
+                    # Standalone comment, just add it
+                    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:
+                            messages.append("  Added blank line before attribute above include")
+                    new_lines.append(current_line)
+                else:
+                    # Standalone attribute, just add it
+                    new_lines.append(current_line)
+
+        # Check if current line is an include directive
+        elif re.match(r'^include::', current_line):
+            # Handle includes inside conditional blocks
+            if in_conditional:
+                # Add blank line between consecutive includes within conditional blocks
+                if prev_line and re.match(r'^include::', prev_line):
+                    new_lines.append("")
+                    changes_made = True
+                    if verbose:
+                        messages.append("  Added blank line between includes in conditional block")
+                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
+                        # This includes adding blank lines between consecutive includes
+                        if (prev_line and
+                            not re.match(r'^\s*$', prev_line)):
+                            new_lines.append("")
+                            changes_made = True
+                            if verbose:
+                                truncated = current_line[:50] + "..." if len(current_line) > 50 else current_line
+                                messages.append(f"  Added blank line before include: {truncated}")
+
+                new_lines.append(current_line)
+
+                # If it's an attribute include near H1, don't add blank line after
+                if not (is_attribute_include and is_near_h1):
+                    # Add blank line after include if next line exists and is not empty and not an include
+                    if (next_line and
+                        not re.match(r'^\s*$', next_line) and
+                        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
+                            messages.append(f"  Added blank line after include: {truncated}")
+
+        else:
+            new_lines.append(current_line)
+
+    # Apply changes if any were made
+    if changes_made:
+        # Clean up any consecutive blank lines we may have added
+        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 not dry_run:
+            try:
+                with open(file_path, 'w', encoding='utf-8') as f:
+                    for line in cleaned_lines:
+                        f.write(line + '\n')
+            except IOError as e:
+                raise IOError(f"Error writing {file_path}: {e}")
+    else:
+        if verbose:
+            messages.append("  No changes needed")
+
+    return changes_made, messages
+
+
+def find_adoc_files(path: Path) -> List[Path]:
+    """Find all .adoc files in the given path"""
+    adoc_files = []
+
+    if path.is_file():
+        if path.suffix == '.adoc':
+            adoc_files.append(path)
+    elif path.is_dir():
+        adoc_files = list(path.rglob('*.adoc'))
+
+    return adoc_files

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/inventory_conditionals.py

@@ -0,0 +1,164 @@
+"""
+Module for inventorying AsciiDoc conditional directives.
+
+Functions:
+- find_adoc_files: Recursively find all .adoc files in a directory.
+- scan_file_for_conditionals: Scan a file for conditional directives.
+- create_inventory: Create an inventory of all conditionals found in .adoc files.
+"""
+
+import re
+from datetime import datetime
+from pathlib import Path
+from collections import defaultdict
+from typing import List, Tuple, Dict, Set
+
+
+# Pattern to match AsciiDoc conditionals
+CONDITIONAL_PATTERN = re.compile(
+    r'^(ifdef|ifndef|endif|ifeval)::(.*)$',
+    re.MULTILINE
+)
+
+
+def find_adoc_files(directory: Path) -> List[Path]:
+    """Find all .adoc files in the given directory recursively."""
+    return sorted(directory.rglob('*.adoc'))
+
+
+def scan_file_for_conditionals(filepath: Path) -> List[Tuple[int, str, str]]:
+    """
+    Scan a file for conditional directives.
+
+    Args:
+        filepath: Path to the .adoc file to scan.
+
+    Returns:
+        A list of tuples: (line_number, directive_type, condition)
+    """
+    results = []
+    try:
+        content = filepath.read_text(encoding='utf-8')
+        for i, line in enumerate(content.splitlines(), start=1):
+            match = CONDITIONAL_PATTERN.match(line.strip())
+            if match:
+                directive_type = match.group(1)
+                condition = match.group(2)
+                results.append((i, directive_type, condition))
+    except Exception as e:
+        print(f"Warning: Could not read {filepath}: {e}")
+    return results
+
+
+def create_inventory(directory: Path, output_dir: Path = None) -> Path:
+    """
+    Create an inventory of all conditionals found in .adoc files.
+
+    Args:
+        directory: Directory to scan for .adoc files.
+        output_dir: Directory to write the inventory file. Defaults to current directory.
+
+    Returns:
+        The path to the created inventory file.
+    """
+    if output_dir is None:
+        output_dir = Path.cwd()
+
+    timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+    output_file = output_dir / f'inventory-{timestamp}.txt'
+
+    adoc_files = find_adoc_files(directory)
+
+    # Track statistics
+    stats: Dict[str, int] = defaultdict(int)
+    conditions_used: Dict[str, List[Tuple[Path, int]]] = defaultdict(list)
+    total_files_with_conditionals = 0
+
+    lines = []
+    lines.append("AsciiDoc Conditionals Inventory")
+    lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    lines.append(f"Directory: {directory.resolve()}")
+    lines.append("=" * 80)
+    lines.append("")
+
+    for filepath in adoc_files:
+        conditionals = scan_file_for_conditionals(filepath)
+        if conditionals:
+            total_files_with_conditionals += 1
+            relative_path = filepath.relative_to(directory)
+            lines.append(f"File: {relative_path}")
+            lines.append("-" * 60)
+
+            for line_num, directive, condition in conditionals:
+                stats[directive] += 1
+                # Extract the condition name (before any brackets)
+                cond_name = condition.split('[')[0] if condition else '(empty)'
+                if directive in ('ifdef', 'ifndef', 'ifeval'):
+                    conditions_used[cond_name].append((relative_path, line_num))
+
+                lines.append(f"  Line {line_num:5d}: {directive}::{condition}")
+
+            lines.append("")
+
+    # Add summary section
+    lines.append("=" * 80)
+    lines.append("SUMMARY")
+    lines.append("=" * 80)
+    lines.append("")
+    lines.append(f"Total .adoc files scanned: {len(adoc_files)}")
+    lines.append(f"Files with conditionals: {total_files_with_conditionals}")
+    lines.append("")
+    lines.append("Directive counts:")
+    for directive in sorted(stats.keys()):
+        lines.append(f"  {directive}: {stats[directive]}")
+    lines.append(f"  Total: {sum(stats.values())}")
+    lines.append("")
+
+    # List unique conditions
+    lines.append("=" * 80)
+    lines.append("UNIQUE CONDITIONS USED")
+    lines.append("=" * 80)
+    lines.append("")
+    for cond in sorted(conditions_used.keys()):
+        occurrences = conditions_used[cond]
+        lines.append(f"  {cond}: {len(occurrences)} occurrences")
+
+    # Write the inventory file
+    output_file.write_text('\n'.join(lines), encoding='utf-8')
+
+    return output_file
+
+
+def get_inventory_stats(directory: Path) -> Dict:
+    """
+    Get statistics about conditionals without writing a file.
+
+    Args:
+        directory: Directory to scan for .adoc files.
+
+    Returns:
+        Dictionary with statistics about conditionals found.
+    """
+    adoc_files = find_adoc_files(directory)
+
+    stats: Dict[str, int] = defaultdict(int)
+    conditions_used: Dict[str, int] = defaultdict(int)
+    files_with_conditionals: Set[Path] = set()
+
+    for filepath in adoc_files:
+        conditionals = scan_file_for_conditionals(filepath)
+        if conditionals:
+            files_with_conditionals.add(filepath)
+            for line_num, directive, condition in conditionals:
+                stats[directive] += 1
+                cond_name = condition.split('[')[0] if condition else '(empty)'
+                if directive in ('ifdef', 'ifndef', 'ifeval'):
+                    conditions_used[cond_name] += 1
+
+    return {
+        'total_files': len(adoc_files),
+        'files_with_conditionals': len(files_with_conditionals),
+        'directive_counts': dict(stats),
+        'total_conditionals': sum(stats.values()),
+        'unique_conditions': dict(conditions_used),
+    }