Merge pull request #23 from JSv4/docs/quickstart-docxodus-default

Update quickstart to feature DocxodusEngine; widen run_redline type hint

Author: JSv4

docs/quickstart.md

@@ -1,31 +1,35 @@
 # Python-Redlines Quickstart
 
 `python-redlines` wraps a C# comparison engine to produce tracked-change redline `.docx`
-files. This guide uses the `XmlPowerToolsEngine` (Open-XML-PowerTools); `DocxodusEngine`
-works the same way.
+files. This guide uses `DocxodusEngine` — the default and recommended engine.
+`XmlPowerToolsEngine` (legacy) shares the same call signature; the only behavioural
+difference is that it silently ignores the keyword arguments shown in Step 4.
 
 ### Step 0: Install
 
 Install the core package plus the engine you want as an extra. No .NET SDK is needed —
 the engine binary is prebuilt and embedded in the wheel.
 
 ```commandline
-pip install python-redlines[ooxmlpowertools]
+pip install python-redlines[docxodus]
 ```
 
+Use `python-redlines[ooxmlpowertools]` for the legacy engine, or `python-redlines[all]`
+for both.
+
 ### Step 1: Import and Initialize the Wrapper
 
 In your Python script or interactive session, import and initialize the wrapper:
 
 ```python
-from python_redlines.engines import XmlPowerToolsEngine
+from python_redlines import DocxodusEngine
 
-wrapper = XmlPowerToolsEngine()
+wrapper = DocxodusEngine()
 ```
 
 ### Step 2: Run Redlines
 
-Use the `run_redline` method to compare documents. You can pass the paths of the `.docx` files or their byte content:
+Use the `run_redline` method to compare documents. You can pass the paths of the `.docx` files (as `str` or `pathlib.Path`) or their byte content:
 
 ```python
 # Example with file paths
@@ -37,12 +41,11 @@ with open('/path/to/original.docx', 'rb') as f:
 with open('/path/to/modified.docx', 'rb') as f:
     modified_bytes = f.read()
 
-# This is a tuple, bytes @ element 0
+# Returns (redline_bytes, stdout, stderr)
 output = wrapper.run_redline('AuthorTag', original_bytes, modified_bytes)
 ```
 
-In both cases, `output` will contain the byte content of the resulting redline - a .docx with changes in tracked 
-changes.
+In both cases, `output[0]` will contain the byte content of the resulting redline — a .docx with changes as Word tracked changes.
 
 ### Step 3: Handle the Output
 
@@ -52,3 +55,20 @@ Process or save the output as needed. For example, to save the redline output to
 with open('/path/to/redline_output.docx', 'wb') as f:
     f.write(output[0])
 ```
+
+### Step 4: Tune the Comparison (optional, DocxodusEngine only)
+
+`DocxodusEngine` accepts keyword arguments to control move detection, granularity, and
+more. See the [main README](../README.md#comparison-settings-docxodusengine-only) for
+the full table.
+
+```python
+output = wrapper.run_redline(
+    'AuthorTag', original_bytes, modified_bytes,
+    detect_moves=True,
+    simplify_move_markup=True,  # required with detect_moves for Word compatibility
+    detail_threshold=0.3,
+)
+```
+
+`XmlPowerToolsEngine` silently ignores these kwargs — switch engines if you need them.

packages/core/src/python_redlines/engines.py

@@ -132,11 +132,11 @@ def _build_command(self, author_tag: str, original_path, modified_path, target_p
         """
         return [self.extracted_binaries_path, author_tag, original_path, modified_path, target_path]
 
-    def run_redline(self, author_tag: str, original: Union[bytes, Path], modified: Union[bytes, Path], **kwargs) \
-            -> Tuple[bytes, Optional[str], Optional[str]]:
+    def run_redline(self, author_tag: str, original: Union[str, bytes, Path], modified: Union[str, bytes, Path],
+                    **kwargs) -> Tuple[bytes, Optional[str], Optional[str]]:
         """
-        Runs the redline binary. The 'original' and 'modified' arguments can be either bytes or file paths.
-        Returns the redline output as bytes.
+        Runs the redline binary. The 'original' and 'modified' arguments can be either bytes or file paths
+        (as ``str`` or ``pathlib.Path``). Returns the redline output as bytes.
 
         Additional keyword arguments are passed to _build_command() for engine-specific options.
         DocxodusEngine supports: detail_threshold, case_insensitive, detect_moves,