rolfedh-doc-utils 0.1.34__tar.gz → 0.1.37__tar.gz

{rolfedh_doc_utils-0.1.34 → rolfedh_doc_utils-0.1.37}/PKG-INFO

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

{rolfedh_doc_utils-0.1.34 → rolfedh_doc_utils-0.1.37}/archive_unused_files.py

@@ -22,6 +22,7 @@ def main():
         epilog='By default, automatically discovers all modules and assemblies directories in the repository.'
     )
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
+    parser.add_argument('--commented', action='store_true', help='Include files that are referenced only in commented lines in the archive operation.')
     parser.add_argument('--scan-dir', action='append', default=[], help='Specific directory to scan (can be used multiple times). If not specified, auto-discovers directories.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
     parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
@@ -35,13 +36,13 @@ def main():
 
     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)
 
-    find_unused_adoc(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+    find_unused_adoc(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files, args.commented)
 
 if __name__ == '__main__':
     main()

{rolfedh_doc_utils-0.1.34 → rolfedh_doc_utils-0.1.37}/archive_unused_images.py

@@ -18,6 +18,7 @@ def main():
     check_version_on_startup()
     parser = argparse.ArgumentParser(description='Archive unused image files.')
     parser.add_argument('--archive', action='store_true', help='Move the files to a dated zip in the archive directory.')
+    parser.add_argument('--commented', action='store_true', help='Include images that are referenced only in commented lines in the archive operation.')
     parser.add_argument('--exclude-dir', action='append', default=[], help='Directory to exclude (can be used multiple times).')
     parser.add_argument('--exclude-file', action='append', default=[], help='File to exclude (can be used multiple times).')
     parser.add_argument('--exclude-list', type=str, help='Path to a file containing directories or files to exclude, one per line.')
@@ -29,13 +30,13 @@ def main():
 
     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)
 
-    find_unused_images(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files)
+    find_unused_images(scan_dirs, archive_dir, args.archive, exclude_dirs, exclude_files, args.commented)
 
 if __name__ == '__main__':
     main()

rolfedh_doc_utils-0.1.37/check_source_directives.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""
+Check Source Directives
+
+Detects code blocks (----) that are missing [source] directive in AsciiDoc files.
+This helps prevent AsciiDoc-to-DocBook XML conversion errors.
+
+Usage:
+  check-source-directives                    # Scan current directory
+  check-source-directives asciidoc          # Scan asciidoc/ directory
+  check-source-directives --fix             # Scan and fix issues in current directory
+  check-source-directives --fix asciidoc    # Scan and fix issues in asciidoc/ directory
+"""
+
+import argparse
+import sys
+from doc_utils.missing_source_directive import find_missing_source_directives
+from doc_utils.version_check import check_version_on_startup
+from doc_utils.version import __version__
+
+# ANSI color codes
+RED = '\033[0;31m'
+YELLOW = '\033[1;33m'
+GREEN = '\033[0;32m'
+NC = '\033[0m'  # No Color
+
+def main():
+    # Check for updates (non-blocking)
+    check_version_on_startup()
+
+    parser = argparse.ArgumentParser(
+        description='Detect code blocks (----) missing [source] directive in AsciiDoc files',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s                    # Scan current directory
+  %(prog)s asciidoc          # Scan asciidoc/ directory
+  %(prog)s --fix             # Scan and fix issues in current directory
+  %(prog)s --fix asciidoc    # Scan and fix issues in asciidoc/ directory
+        """
+    )
+    parser.add_argument('directory', nargs='?', default='.',
+                        help='Directory to scan (default: current directory)')
+    parser.add_argument('--fix', action='store_true',
+                        help='Automatically insert [source] directives where missing')
+    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__}')
+
+    args = parser.parse_args()
+
+    mode = "Fixing" if args.fix else "Scanning for"
+    print(f"{mode} code blocks missing [source] directive in: {args.directory}")
+    print("=" * 64)
+    print()
+
+    try:
+        results = find_missing_source_directives(
+            scan_dir=args.directory,
+            auto_fix=args.fix
+        )
+    except ValueError as e:
+        print(f"{RED}Error: {e}{NC}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"{RED}Unexpected error: {e}{NC}", file=sys.stderr)
+        sys.exit(1)
+
+    # Display results
+    for file_info in results['file_details']:
+        filepath = file_info['filepath']
+        issues = file_info['issues']
+
+        print(f"{YELLOW}File: {filepath}{NC}")
+
+        for issue in issues:
+            print(f"  {RED}Line {issue['line_num']}:{NC} Code block without [source] directive")
+            print(f"    Previous line ({issue['prev_line_num']}): {issue['prev_line']}")
+            print()
+
+        if args.fix:
+            if file_info.get('fixed'):
+                print(f"  {GREEN}✓ Fixed {len(issues)} issue(s){NC}")
+            elif 'error' in file_info:
+                print(f"  {RED}✗ Failed to fix file: {file_info['error']}{NC}")
+            print()
+
+    # Summary
+    print("=" * 64)
+    if results['total_issues'] == 0:
+        print(f"{GREEN}✓ No issues found!{NC}")
+        sys.exit(0)
+    else:
+        if args.fix:
+            print(f"{GREEN}Fixed {results['total_issues']} code block(s) in {results['files_fixed']} file(s){NC}")
+            sys.exit(0)
+        else:
+            print(f"{RED}Found {results['total_issues']} code block(s) missing [source] directive in {results['files_with_issues']} file(s){NC}")
+            print(f"\nRun with --fix to automatically fix these issues")
+            sys.exit(1)
+
+if __name__ == '__main__':
+    main()

rolfedh_doc_utils-0.1.37/convert_tables_to_deflists.py

@@ -0,0 +1,479 @@
+#!/usr/bin/env python3
+"""
+convert-tables-to-deflists: Convert AsciiDoc tables to definition lists.
+
+Converts 2-column AsciiDoc tables to definition list format, where:
+- The first column becomes the term
+- The second column becomes the definition
+
+Tables with more than 2 columns are skipped (use --columns to specify which
+columns to use as term and definition).
+
+Usage:
+    convert-tables-to-deflists [OPTIONS] [PATH]
+
+Examples:
+    # Preview changes (dry-run mode)
+    convert-tables-to-deflists .
+
+    # Apply changes to all .adoc files
+    convert-tables-to-deflists --apply .
+
+    # Process a single file
+    convert-tables-to-deflists --apply path/to/file.adoc
+
+    # Use columns 1 and 3 for 3-column tables
+    convert-tables-to-deflists --columns 1,3 .
+
+    # Skip tables with headers
+    convert-tables-to-deflists --skip-header-tables .
+"""
+
+import argparse
+import sys
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from callout_lib.table_parser import TableParser, AsciiDocTable
+from doc_utils.version import __version__
+from doc_utils.file_utils import parse_exclude_list_file
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+    RED = '\033[0;31m'
+    GREEN = '\033[0;32m'
+    YELLOW = '\033[1;33m'
+    BLUE = '\033[0;34m'
+    CYAN = '\033[0;36m'
+    NC = '\033[0m'  # No Color
+
+
+def print_colored(message: str, color: str = Colors.NC) -> None:
+    """Print a message with optional color."""
+    print(f"{color}{message}{Colors.NC}")
+
+
+class TableToDeflistConverter:
+    """Converts AsciiDoc tables to definition lists."""
+
+    def __init__(self, dry_run: bool = True, verbose: bool = False,
+                 columns: Optional[Tuple[int, int]] = None,
+                 skip_header_tables: bool = False,
+                 skip_callout_tables: bool = True):
+        """
+        Initialize the converter.
+
+        Args:
+            dry_run: If True, don't modify files (preview mode)
+            verbose: If True, show detailed output
+            columns: Tuple of (term_col, def_col) for multi-column tables (1-indexed)
+            skip_header_tables: If True, skip tables that have header rows
+            skip_callout_tables: If True, skip tables that look like callout tables
+        """
+        self.dry_run = dry_run
+        self.verbose = verbose
+        self.columns = columns  # 1-indexed column numbers
+        self.skip_header_tables = skip_header_tables
+        self.skip_callout_tables = skip_callout_tables
+        self.parser = TableParser()
+        self.files_processed = 0
+        self.files_modified = 0
+        self.tables_converted = 0
+
+    def find_adoc_files(self, path: Path, exclude_dirs: List[str] = None,
+                        exclude_files: List[str] = None) -> List[Path]:
+        """Find all .adoc files in the given path."""
+        exclude_dirs = exclude_dirs or []
+        exclude_files = exclude_files or []
+
+        if path.is_file():
+            return [path] if path.suffix == '.adoc' else []
+
+        adoc_files = []
+        for adoc_file in path.rglob('*.adoc'):
+            # Skip excluded directories
+            if any(excl in str(adoc_file) for excl in exclude_dirs):
+                continue
+            # Skip excluded files
+            if any(excl in str(adoc_file) for excl in exclude_files):
+                continue
+            # Skip symlinks
+            if adoc_file.is_symlink():
+                continue
+            adoc_files.append(adoc_file)
+
+        return sorted(adoc_files)
+
+    def _should_skip_table(self, table: AsciiDocTable) -> Tuple[bool, str]:
+        """
+        Determine if a table should be skipped.
+
+        Returns:
+            Tuple of (should_skip, reason)
+        """
+        # Skip empty tables
+        if not table.rows:
+            return True, "empty table"
+
+        # Skip callout tables (they're handled by convert-callouts-to-deflist)
+        if self.skip_callout_tables:
+            if self.parser.is_callout_table(table) or self.parser.is_3column_callout_table(table):
+                return True, "callout table (use convert-callouts-to-deflist)"
+
+        # Check column count
+        if table.rows:
+            first_row_cols = len(table.rows[0].cells)
+
+            # If specific columns are specified, verify they exist
+            if self.columns:
+                term_col, def_col = self.columns
+                if term_col > first_row_cols or def_col > first_row_cols:
+                    return True, f"specified columns ({term_col}, {def_col}) exceed table columns ({first_row_cols})"
+            else:
+                # Default: only process 2-column tables
+                if first_row_cols != 2:
+                    return True, f"{first_row_cols}-column table (use --columns to specify term and definition columns)"
+
+        # Check for header row
+        if self.skip_header_tables and self.parser._has_header_row(table):
+            return True, "table has header row"
+
+        return False, ""
+
+    def _convert_table_to_deflist(self, table: AsciiDocTable) -> List[str]:
+        """
+        Convert a table to definition list format.
+
+        Args:
+            table: The AsciiDocTable to convert
+
+        Returns:
+            List of lines representing the definition list
+        """
+        output = []
+
+        # Determine which columns to use (0-indexed internally)
+        if self.columns:
+            term_idx = self.columns[0] - 1  # Convert to 0-indexed
+            def_idx = self.columns[1] - 1
+        else:
+            term_idx = 0
+            def_idx = 1
+
+        # Check if table has a header row
+        has_header = self.parser._has_header_row(table)
+        data_rows = table.rows[1:] if has_header else table.rows
+
+        for row in data_rows:
+            # Verify row has enough cells
+            if len(row.cells) <= max(term_idx, def_idx):
+                continue
+
+            # Add conditionals before row
+            if row.conditionals_before:
+                output.extend(row.conditionals_before)
+
+            # Get term (first specified column)
+            term_cell = row.cells[term_idx]
+            term = ' '.join(line.strip() for line in term_cell.content if line.strip())
+
+            # Get definition (second specified column)
+            def_cell = row.cells[def_idx]
+            def_lines = def_cell.content
+
+            # Create definition list entry
+            if term:
+                output.append(f'{term}::')
+
+                # Add definition lines
+                first_content_line = True
+                for line in def_lines:
+                    stripped = line.strip()
+
+                    # Handle conditional directives
+                    if stripped.startswith(('ifdef::', 'ifndef::', 'endif::')):
+                        output.append(line)
+                        continue
+
+                    # Skip empty lines within definition but track them
+                    if not stripped:
+                        continue
+
+                    # First content line gets no indent, subsequent lines do
+                    if first_content_line:
+                        output.append(stripped)
+                        first_content_line = False
+                    else:
+                        output.append(f'+\n{stripped}')
+
+                # Add blank line after entry
+                output.append('')
+
+            # Add conditionals after row
+            if row.conditionals_after:
+                output.extend(row.conditionals_after)
+
+        # Remove trailing blank line if present
+        if output and not output[-1].strip():
+            output.pop()
+
+        return output
+
+    def process_file(self, file_path: Path) -> int:
+        """
+        Process a single file, converting tables to definition lists.
+
+        Args:
+            file_path: Path to the .adoc file
+
+        Returns:
+            Number of tables converted
+        """
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                lines = [line.rstrip('\n') for line in f]
+        except Exception as e:
+            print_colored(f"Error reading {file_path}: {e}", Colors.RED)
+            return 0
+
+        original_lines = lines.copy()
+        tables = self.parser.find_tables(lines)
+        conversions = 0
+
+        # Process tables in reverse order to preserve line numbers
+        for table in reversed(tables):
+            should_skip, reason = self._should_skip_table(table)
+
+            if should_skip:
+                if self.verbose:
+                    print(f"  Skipping table at line {table.start_line + 1}: {reason}")
+                continue
+
+            # Convert the table
+            deflist_lines = self._convert_table_to_deflist(table)
+
+            if deflist_lines:
+                # Replace table with definition list
+                lines[table.start_line:table.end_line + 1] = deflist_lines
+                conversions += 1
+
+                if self.verbose:
+                    print(f"  Converted table at line {table.start_line + 1}")
+
+        # Write changes if not in dry-run mode
+        if conversions > 0:
+            if self.dry_run:
+                print_colored(f"Would modify: {file_path} ({conversions} table(s))", Colors.YELLOW)
+            else:
+                try:
+                    with open(file_path, 'w', encoding='utf-8') as f:
+                        f.write('\n'.join(lines) + '\n')
+                    print_colored(f"Modified: {file_path} ({conversions} table(s))", Colors.GREEN)
+                except Exception as e:
+                    print_colored(f"Error writing {file_path}: {e}", Colors.RED)
+                    return 0
+
+        return conversions
+
+    def process_path(self, path: Path, exclude_dirs: List[str] = None,
+                     exclude_files: List[str] = None) -> None:
+        """
+        Process all .adoc files in the given path.
+
+        Args:
+            path: File or directory path to process
+            exclude_dirs: List of directory patterns to exclude
+            exclude_files: List of file patterns to exclude
+        """
+        adoc_files = self.find_adoc_files(path, exclude_dirs, exclude_files)
+
+        if not adoc_files:
+            print_colored("No .adoc files found.", Colors.YELLOW)
+            return
+
+        if self.dry_run:
+            print_colored("DRY RUN MODE - No files will be modified", Colors.YELLOW)
+            print()
+
+        for file_path in adoc_files:
+            self.files_processed += 1
+            conversions = self.process_file(file_path)
+
+            if conversions > 0:
+                self.files_modified += 1
+                self.tables_converted += conversions
+
+        # Print summary
+        print()
+        print(f"Processed {self.files_processed} file(s)")
+        print(f"Tables converted: {self.tables_converted}")
+        print(f"Files {'would be ' if self.dry_run else ''}modified: {self.files_modified}")
+
+        if self.dry_run and self.files_modified > 0:
+            print()
+            print_colored("DRY RUN - No files were modified. Use --apply to apply changes.", Colors.YELLOW)
+
+
+def parse_columns(columns_str: str) -> Tuple[int, int]:
+    """
+    Parse a columns specification like "1,3" into a tuple.
+
+    Args:
+        columns_str: String like "1,3" specifying term and definition columns
+
+    Returns:
+        Tuple of (term_column, definition_column) as 1-indexed integers
+
+    Raises:
+        argparse.ArgumentTypeError: If the format is invalid
+    """
+    try:
+        parts = columns_str.split(',')
+        if len(parts) != 2:
+            raise ValueError("Expected exactly two column numbers")
+        term_col = int(parts[0].strip())
+        def_col = int(parts[1].strip())
+        if term_col < 1 or def_col < 1:
+            raise ValueError("Column numbers must be 1 or greater")
+        if term_col == def_col:
+            raise ValueError("Term and definition columns must be different")
+        return (term_col, def_col)
+    except ValueError as e:
+        raise argparse.ArgumentTypeError(
+            f"Invalid columns format '{columns_str}': {e}. "
+            "Use format like '1,2' or '1,3' (1-indexed column numbers)"
+        )
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        description='Convert AsciiDoc tables to definition lists.',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Preview changes (default dry-run mode)
+  convert-tables-to-deflists .
+
+  # Apply changes to all .adoc files
+  convert-tables-to-deflists --apply .
+
+  # Process a single file
+  convert-tables-to-deflists --apply path/to/file.adoc
+
+  # For 3-column tables, use columns 1 and 3
+  convert-tables-to-deflists --columns 1,3 .
+
+  # Skip tables that have header rows
+  convert-tables-to-deflists --skip-header-tables .
+
+Notes:
+  - By default, only 2-column tables are converted
+  - Callout tables are automatically skipped (use convert-callouts-to-deflist)
+  - Use --columns to specify which columns to use for multi-column tables
+  - The first specified column becomes the term, the second becomes the definition
+"""
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {__version__}'
+    )
+
+    parser.add_argument(
+        'path',
+        nargs='?',
+        default='.',
+        help='File or directory to process (default: current directory)'
+    )
+
+    parser.add_argument(
+        '--apply',
+        action='store_true',
+        help='Apply changes (default is dry-run mode)'
+    )
+
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Show detailed output'
+    )
+
+    parser.add_argument(
+        '--columns',
+        type=parse_columns,
+        metavar='TERM,DEF',
+        help='Column numbers to use as term and definition (1-indexed, e.g., "1,3")'
+    )
+
+    parser.add_argument(
+        '--skip-header-tables',
+        action='store_true',
+        help='Skip tables that have header rows'
+    )
+
+    parser.add_argument(
+        '--include-callout-tables',
+        action='store_true',
+        help='Include callout tables (normally skipped)'
+    )
+
+    parser.add_argument(
+        '--exclude-dir',
+        action='append',
+        default=[],
+        metavar='DIR',
+        help='Directory pattern to exclude (can be specified multiple times)'
+    )
+
+    parser.add_argument(
+        '--exclude-file',
+        action='append',
+        default=[],
+        metavar='FILE',
+        help='File pattern to exclude (can be specified multiple times)'
+    )
+
+    parser.add_argument(
+        '--exclude-list',
+        type=Path,
+        metavar='FILE',
+        help='Path to file containing exclusion patterns (one per line)'
+    )
+
+    args = parser.parse_args()
+
+    # Parse exclusion list 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)
+
+    # Create converter
+    converter = TableToDeflistConverter(
+        dry_run=not args.apply,
+        verbose=args.verbose,
+        columns=args.columns,
+        skip_header_tables=args.skip_header_tables,
+        skip_callout_tables=not args.include_callout_tables
+    )
+
+    # Process files
+    path = Path(args.path)
+    if not path.exists():
+        print_colored(f"Error: Path does not exist: {path}", Colors.RED)
+        return 1
+
+    converter.process_path(path, exclude_dirs, exclude_files)
+
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())