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

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

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

rolfedh_doc_utils-0.1.41/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.41}/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.41"
 
 def get_version():
     """Return the current version string."""

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

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.41}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rolfedh-doc-utils"
-version = "0.1.40"
+version = "0.1.41"
 description = "CLI tools for AsciiDoc documentation projects"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -33,10 +33,11 @@ convert-freemarker-to-asciidoc = "convert_freemarker_to_asciidoc:main"
 inventory-conditionals = "inventory_conditionals:main"
 find-duplicate-content = "find_duplicate_content:main"
 find-duplicate-includes = "find_duplicate_includes:main"
+insert-abstract-role = "insert_abstract_role:main"
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["doc_utils*", "callout_lib*"]
 
 [tool.setuptools]
-py-modules = ["doc_utils_cli", "find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes", "extract_link_attributes", "validate_links", "convert_callouts_to_deflist", "convert_callouts_interactive", "check_source_directives", "convert_tables_to_deflists", "check_published_links", "convert_freemarker_to_asciidoc", "inventory_conditionals", "find_duplicate_content", "find_duplicate_includes"]
+py-modules = ["doc_utils_cli", "find_unused_attributes", "check_scannability", "archive_unused_files", "archive_unused_images", "format_asciidoc_spacing", "replace_link_attributes", "extract_link_attributes", "validate_links", "convert_callouts_to_deflist", "convert_callouts_interactive", "check_source_directives", "convert_tables_to_deflists", "check_published_links", "convert_freemarker_to_asciidoc", "inventory_conditionals", "find_duplicate_content", "find_duplicate_includes", "insert_abstract_role"]

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.41}/rolfedh_doc_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rolfedh-doc-utils
-Version: 0.1.40
+Version: 0.1.41
 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.41}/rolfedh_doc_utils.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ find_duplicate_content.py
 find_duplicate_includes.py
 find_unused_attributes.py
 format_asciidoc_spacing.py
+insert_abstract_role.py
 inventory_conditionals.py
 pyproject.toml
 replace_link_attributes.py
@@ -33,6 +34,7 @@ doc_utils/duplicate_includes.py
 doc_utils/extract_link_attributes.py
 doc_utils/file_utils.py
 doc_utils/format_asciidoc_spacing.py
+doc_utils/insert_abstract_role.py
 doc_utils/inventory_conditionals.py
 doc_utils/missing_source_directive.py
 doc_utils/replace_link_attributes.py

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.41}/rolfedh_doc_utils.egg-info/entry_points.txt

@@ -14,6 +14,7 @@ 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
 inventory-conditionals = inventory_conditionals:main
 replace-link-attributes = replace_link_attributes:main
 validate-links = validate_links:main

{rolfedh_doc_utils-0.1.40 → rolfedh_doc_utils-0.1.41}/rolfedh_doc_utils.egg-info/top_level.txt

@@ -15,6 +15,7 @@ find_duplicate_content
 find_duplicate_includes
 find_unused_attributes
 format_asciidoc_spacing
+insert_abstract_role
 inventory_conditionals
 replace_link_attributes
 validate_links