Improve/fix logging

This patch improves/fixes logs:

- Skip backup documentation directories to avoid showing unnecessary
  errors
- Prevent concurrent file edits
- Fix incorrect error messages when there's nothing wrong with the
  source files
- Remove duplicated log messages
- Show correct status of applied fixes

AI: Code generated by Cursor

Author: Akrog

scripts/rhoso_adoc_docs_to_text.py

@@ -25,6 +25,8 @@
 import re
 import subprocess
 import tempfile
+import fcntl
+import time
 
 LOG = logging.getLogger()
 logging.basicConfig(level=logging.INFO)
@@ -1679,58 +1681,125 @@ def preprocess_adoc_tables(
     return result, fixes
 
 
+class FileLock:
+    """Context manager for file locking to prevent concurrent modifications.
+
+    Uses fcntl-based advisory locks on Linux systems. Creates a .lock file
+    next to the target file for locking purposes.
+    """
+
+    def __init__(
+        self, file_path: Path, timeout: int = 300, check_interval: float = 0.1
+    ):
+        """Initialize the file lock.
+
+        Args:
+            file_path: Path to the file to lock
+            timeout: Maximum time in seconds to wait for lock (default: 300s = 5 min)
+            check_interval: Time in seconds between lock acquisition attempts (default: 0.1s)
+        """
+        self.file_path = file_path
+        self.lock_path = file_path.parent / f".{file_path.name}.lock"
+        self.timeout = timeout
+        self.check_interval = check_interval
+        self.lock_file = None
+
+    def __enter__(self):
+        """Acquire the file lock."""
+        start_time = time.time()
+        while True:
+            try:
+                # Open lock file (create if it doesn't exist)
+                self.lock_file = open(self.lock_path, "w")
+                # Try to acquire exclusive lock (non-blocking)
+                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                # Successfully acquired lock
+                LOG.debug(f"Acquired lock for {self.file_path}")
+                return self
+            except (IOError, OSError):
+                # Lock is held by another process
+                if time.time() - start_time > self.timeout:
+                    if self.lock_file:
+                        self.lock_file.close()
+                    raise TimeoutError(
+                        f"Could not acquire lock for {self.file_path} after {self.timeout}s"
+                    )
+                # Wait and retry
+                time.sleep(self.check_interval)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Release the file lock."""
+        if self.lock_file:
+            try:
+                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_UN)
+                self.lock_file.close()
+                LOG.debug(f"Released lock for {self.file_path}")
+                # Try to remove the lock file (best effort)
+                try:
+                    self.lock_path.unlink()
+                except Exception:
+                    pass
+            except Exception as e:
+                LOG.warning(f"Error releasing lock for {self.file_path}: {e}")
+
+
 def fix_adoc_file(file_path: Path) -> list[str]:
     """Apply all AsciiDoc fixes to a source file and report changes.
 
     This function reads an .adoc file, applies all preprocessing fixes,
     writes the changes back to the file if any fixes were made, and
     returns a list of descriptions of what was fixed.
 
+    Uses file locking to prevent concurrent modifications when multiple
+    workers are processing files in parallel.
+
     Args:
         file_path: Path to the .adoc file to fix
 
     Returns:
         List of fix descriptions (empty if no fixes were needed)
     """
-    try:
-        with open(file_path, "r", encoding="utf-8") as f:
-            original_content = f.read()
-    except Exception as e:
-        LOG.error(f"Failed to read {file_path}: {e}")
-        return []
+    # Acquire exclusive lock before processing the file
+    with FileLock(file_path):
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                original_content = f.read()
+        except Exception as e:
+            LOG.error(f"Failed to read {file_path}: {e}")
+            return []
 
-    content = original_content
-    all_fixes = []
+        content = original_content
+        all_fixes = []
 
-    # Apply all preprocessing steps
-    content, fixes = preprocess_adoc_link_brackets(content, file_path)
-    all_fixes.extend(fixes)
+        # Apply all preprocessing steps
+        content, fixes = preprocess_adoc_link_brackets(content, file_path)
+        all_fixes.extend(fixes)
 
-    content, fixes = preprocess_adoc_callout_numbering(content, file_path)
-    all_fixes.extend(fixes)
+        content, fixes = preprocess_adoc_callout_numbering(content, file_path)
+        all_fixes.extend(fixes)
 
-    content, fixes = preprocess_adoc_callout_placement(content, file_path)
-    all_fixes.extend(fixes)
+        content, fixes = preprocess_adoc_callout_placement(content, file_path)
+        all_fixes.extend(fixes)
 
-    content, fixes = preprocess_adoc_callouts(content, file_path)
-    all_fixes.extend(fixes)
+        content, fixes = preprocess_adoc_callouts(content, file_path)
+        all_fixes.extend(fixes)
 
-    content, fixes = preprocess_adoc_callout_spacing(content, file_path)
-    all_fixes.extend(fixes)
+        content, fixes = preprocess_adoc_callout_spacing(content, file_path)
+        all_fixes.extend(fixes)
 
-    content, fixes = preprocess_adoc_tables(content, file_path)
-    all_fixes.extend(fixes)
+        content, fixes = preprocess_adoc_tables(content, file_path)
+        all_fixes.extend(fixes)
 
-    # Only write back if changes were made
-    if content != original_content:
-        try:
-            with open(file_path, "w", encoding="utf-8") as f:
-                f.write(content)
-        except Exception as e:
-            LOG.error(f"Failed to write fixes to {file_path}: {e}")
-            return []
+        # Only write back if changes were made
+        if content != original_content:
+            try:
+                with open(file_path, "w", encoding="utf-8") as f:
+                    f.write(content)
+            except Exception as e:
+                LOG.error(f"Failed to write fixes to {file_path}: {e}")
+                return []
 
-    return all_fixes
+        return all_fixes
 
 
 def fix_adoc_files_in_directory(base_dir: Path) -> dict[Path, list[str]]:
@@ -2589,6 +2658,8 @@ def convert(self, input_path: Path, output_path: Path) -> dict[Path, list[str]]:
 
                 LOG.info("Successfully converted: %s -> %s", input_path, output_path)
 
+                return fixes_by_file
+
             except Exception as e:
                 LOG.error(
                     "Failed to convert: %s -> %s (%s)", input_path, output_path, e
@@ -2873,7 +2944,8 @@ def convert(self, input_path: Path, output_path: Path) -> None:
                         all_fixes[file_path] = fixes
             except Exception as e:
                 failed_conversions.append((str(input_path), str(e)))
-                LOG.error("Continuing with next document after failure...")
+                LOG.error("Failed to convert %s: %s", input_path, str(e))
+                LOG.error("Continuing with next document...")
 
     if args.relnotes_dir:
         relnotes_converter = RelNotesConverter(attributes_file=args.attributes_file)
@@ -2891,7 +2963,8 @@ def convert(self, input_path: Path, output_path: Path) -> None:
                         all_fixes[file_path] = fixes
             except Exception as e:
                 failed_conversions.append((str(input_path), str(e)))
-                LOG.error("Continuing with next document after failure...")
+                LOG.error("Failed to convert %s: %s", input_path, str(e))
+                LOG.error("Continuing with next document...")
 
     # Print summary
     LOG.info("\n" + "=" * 80)