Added great readme docs and quick start.

Author: JSv4

.gitignore

@@ -14,7 +14,7 @@ csproj/obj/*
 .Python
 build/
 develop-eggs/
-dist/
+src/python_redlines/dist/
 downloads/
 eggs/
 .eggs/

LICENSE.txt LICENSE.mdLICENSE.txt renamed to LICENSE.md

@@ -1,74 +1,135 @@
-# Python Redlines
+# Python-Redlines: Docx Redlines (Tracked Changes) for the Python Ecosystem
 
-[![PyPI - Version](https://img.shields.io/pypi/v/python-redlines.svg)](https://pypi.org/project/python-redlines)
-[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-redlines.svg)](https://pypi.org/project/python-redlines)
+## Project Goal - Democratizing DOCX Comparisons
 
------
+The main goal of this project is to address the significant gap in the open-source ecosystem around `.docx` document
+comparison tools. Currently, the process of comparing and generating redline documents (documents that highlight 
+changes between versions) is complex and largely dominated by commercial software. These 
+tools, while effective, often come with cost barriers and limitations in terms of accessibility and integration 
+flexibility.
 
-**Table of Contents**
+`Python-redlines` aims to democratize the ability to run tracked change redlines for .docx, providing the 
+open-source community with a tool to create `.docx` redlines without the need for commercial software. This will let
+more legal hackers and hobbyist innovators experiment and create tooling for enterprise and legal.
 
-- [Installation](#installation)
-- [License](#license)
+## Project Roadmap
 
-## Installation
+### Step 1. Open-XML-PowerTools `WmlComparer` Wrapper
 
-```console
-pip install python-redlines
-```
+The [Open-XML-PowerTools](https://github.com/OpenXmlDev/Open-Xml-PowerTools) project historically offered a solid 
+foundation for working with `.docx` files and has an excellent (if imperfect) comparison engine in its `WmlComparer` 
+class. However, Microsoft archived the repository almost five years ago, and a forked repo is not being actively 
+maintained, as its most recent commits dates from 2 years ago and the repo issues list is disabled.
 
-## License
+As a first step, our project aims to bring the existing capabilities of WmlCompare into the Python world. Thankfully, 
+XML Power Tools is full cross-platform as it is written in .NET and compiles with the still-maintained .NET 8. The
+resulting binaries can be compiled for the latest versions of Windows and Linux (Ubuntu specifically, though other
+distributions should work fine too). 
 
-`python-redlines` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+The initial release has a single engine `XmlPowerToolsEngine`, which is just a Python wrapper for a simple C# utility
+written to leverage WmlComparer for 1-to-1 redlines. We hope this provides a stop-gap capability to Python developers 
+seeking .docx redline capabilities. 
 
-Usage:
+**Note**, we don't plan to fork or maintain Open-XML-PowerTools. [Version 4.4.0](https://www.nuget.org/packages/Open-Xml-PowerTools/), 
+which appears to only be compatible with [Open XML SDK < 3.0.0](https://www.nuget.org/packages/DocumentFormat.OpenXml) works
+for now, it needs to be made compatible with the latest versions of the Open XML SDK to extend its life. There are 
+also some [issues](https://github.com/dotnet/Open-XML-SDK/issues/1634) it seems the only maintainer of 
+Open-XML-PowerTools probably won't fix, and understanding the existing code base is no small task.
 
-Setup project and create .net project in dir
-```
-dotnet new console
-```
+### Step 2. Pure Python Comparison Engine
 
-Build app
+Looking towards the future, rather than reverse engineer `WmlComparer` and maintain a C# codebase, we envision a 
+comparison engine written in python. We've done some experimentation with [`xmldiff`](https://github.com/Shoobx/xmldiff)
+as the engine to compare the underlying xml of docx files. Specifically, we've built a prototype to unzip `.docx` files, 
+execute an xml comparison using `xmldiff`, and then reconstructed a tracked changes docx with the proper Open XML
+(ooxml) tracked change tags. Preliminary experimentation with this approach has shown promise, indicating its 
+feasibility for handling modifications such as simple span inserts and deletes.
 
-```
-dotnet build
-```
+However, this ambitious endeavor is not without its challenges. The intricacies of `.docx` files and the potential for 
+complex, corner-case scenarios necessitate a thoughtful and thorough development process. In the interim, `WmlComparer`
+is a great solution as it has clearly been built to account for many such corner cases, through a development process
+that clearly was influenced by issues discovered by a large user base. The XMLDiff engine will take some time to reach
+a level of maturity similar to WmlComparer. At the moment it is NOT included.
 
-Run via dotnet console
-```
-dotnet run scrudato@umich.edu "/home/jman/Downloads/NVCA-Model-Document-Certificate-of-Incorporation.docx" "/home/jman/Downloads/Modified.docx" "/home/jman/Downloads/redline.docx"
-```
+## Getting started
 
-Package for linux
-```
-dotnet publish -c release -r linux-x64 --self-contained
-```
+If you just want to use the tool, jump into our [quickstart guide](docs/quickstart.md).
 
-Package for windows
-```
-dotnet public -c release -r win-x64 --self-contained
-```
+## Architecture Overview
 
-"Install" on Linux
+`XmlPowerToolsEngine` is a Python wrapper class for the `redlines` C# command-line tool, source of which is available in 
+[./csproj/Program.cs](./csproj/Program.cs). The redlines utility and wrapper let you compare two docx files and 
+show the differences in tracked changes (a "redline" document).
 
-1. Install .net for Linux (whatever distro you're using)
-2. Copy the Release contents from linux-x64 folder
-3. run `chmod 777 ./redlines`
-4. Then you can run `./redlines original_path.docx modified_path.docx`
+### C# Functionality
 
-More complete package and install directions: 
+The `redlines` C# utility is a command line tool that requires four arguments:
+1. `author_tag` - A tag to identify the author of the changes.
+2. `original_path.docx` - Path to the original document.
+3. `modified_path.docx` - Path to the modified document.
+4. `redline_path.docx` - Path where the redlined document will be saved.
 
-https://ttu.github.io/dotnet-core-self-contained-deployments/
+The Python wrapper, `XmlPowerToolsEngine` and its main method `run_redlines()`, simplifies the use of `redlines` by 
+orchestrating its execution with Python and letting you pass in bytes or file paths for the original and modified 
+documents.
 
-Archive and zip the release folder contents as .tar.gz, then distribute the archive. User install instructions would be:
+### Packaging
 
-```commandline
-$ mkdir redlines && cd redlines
-$ wget <github release url>
-$ tar -zxvf redlines-linux-x64.tar.gz
-$ chmod +x redlines
-$ ./redlines <author_tag> <original_path.docx> <modified_path.docx> <redline_path.docx>
+The project is structured as follows:
+```
+python-redlines/
+│
+├── csproj/
+│   ├── bin/
+│   ├── obj/
+│   ├── Program.cs
+│   ├── redlines.csproj
+│   └── redlines.sln
+│
+├── docs/
+│   ├── developer-guide.md
+│   └── quickstart.md
+│
+├── src/
+│   └── python_redlines/
+│       ├── bin/
+│       │   └── .gitignore
+│       ├── dist/
+│       │   ├── .gitignore
+│       │   ├── linux-x64-0.0.1.tar.gz
+│       │   └── win-x64-0.0.1.zip
+│       ├── __about__.py
+│       ├── __init__.py
+│       └── engines.py
+│
+├── tests/
+|   ├── fixtures/
+|   ├── test_openxml_differ.py
+|   └── __init__.py
+|
+├── .gitignore
+├── build_differ.py
+├── extract_version.py
+├── License.md
+├── pyproject.toml
+└── README.md
 ```
 
-"Install" on Windows
+- `src/your_package/`: Contains the Python wrapper code.
+- `dist/`: Contains the zipped C# binaries for different platforms.
+- `bin/`: Target directory for extracted binaries.
+- `tests/`: Contains test cases and fixtures for the wrapper.
+
+### Detailed Explanation and Dev Setup
+
+If you want to contribute to the library or want to dive into some of the C# packaging architecture, go to our
+[developer guide](docs/developer-guide.md).
+
+## Additional Information
+
+- **Contributing**: Contributions to the project should follow the established coding and documentation standards.
+- **Issues and Support**: For issues, feature requests, or support, please use the project's issue tracker on GitHub.
+
+## License
 
-TODO - run through this and document
+MIT

README.md

@@ -54,11 +54,11 @@ def main():
 
     # Compress the Linux build
     linux_build_dir = './csproj/bin/Release/net8.0/linux-x64'
-    compress_files(linux_build_dir, f"./src/python_redlines/bin/linux-x64-{version}.tar.gz")
+    compress_files(linux_build_dir, f"./src/python_redlines/dist/linux-x64-{version}.tar.gz")
 
     # Compress the Windows build
     windows_build_dir = './csproj/bin/Release/net8.0/win-x64'
-    compress_files(windows_build_dir, f"./src/python_redlines/bin/win-x64-{version}.zip")
+    compress_files(windows_build_dir, f"./src/python_redlines/dist/win-x64-{version}.zip")
 
     print("Build and compression complete.")
 

build_differ.py

@@ -29,19 +29,16 @@ static void Main(string[] args)
             var originalBytes = File.ReadAllBytes(originalFilePath);
             var modifiedBytes = File.ReadAllBytes(modifiedFilePath);
             var originalDocument = new WmlDocument(originalFilePath, originalBytes);
-            Console.WriteLine(originalDocument);
             var modifiedDocument = new WmlDocument(modifiedFilePath, modifiedBytes);
-            Console.WriteLine(modifiedDocument);
+
             var comparisonSettings = new WmlComparerSettings
             {
                 AuthorForRevisions = authorTag,
                 DetailThreshold = 0
             };
 
             var comparisonResults = WmlComparer.Compare(originalDocument, modifiedDocument, comparisonSettings);
-            Console.WriteLine(comparisonResults);
             var revisions = WmlComparer.GetRevisions(comparisonResults, comparisonSettings);
-            Console.WriteLine(revisions);
 
             // Output results
             Console.WriteLine($"Revisions found: {revisions.Count}");

csproj/Program.cs

@@ -0,0 +1,114 @@
+# Developer Guide for RedlinesWrapper
+
+## Prerequisites
+
+- Python 3.7 or higher installed
+- .NET SDK for building C# binaries or .NET Runtime to run them
+- Hatch for Python environment and package management
+
+## Setting Up the Project
+
+### Step 1: Clone the Repository
+
+Clone the RedlinesWrapper repository to your local
+
+machine. Use Git to clone the repository using the following command:
+
+```bash
+git clone [URL_OF_YOUR_REPOSITORY]
+cd [REPOSITORY_NAME]
+```
+
+Replace `[URL_OF_YOUR_REPOSITORY]` with the actual URL of your repository and `[REPOSITORY_NAME]` with the name of the directory where your repository is cloned.
+
+### Step 2: Install Hatch
+
+If Hatch is not already installed, install it using pip:
+
+```bash
+pip install hatch hatchling
+```
+
+### Step 3: Create and Activate the Virtual Environment
+
+Inside the project directory, create a virtual environment using Hatch:
+
+```bash
+hatch env create
+```
+
+Activate the virtual environment:
+
+```bash
+hatch shell
+```
+
+### Step 4: Install Dependencies
+
+Install the necessary Python dependencies:
+
+```bash
+pip install .[dev]
+```
+
+## Building the C# Binaries
+
+You can use the binaries distributed with the project, or, if you want to build new binaries for some reason, you can
+use our build script, integrated as a hatch tool. 
+
+```bash
+hatch run build
+```
+
+### Under the Hood
+
+We're just using dotnet to build binaries for [Program.cs](csproj/Program.cs), a command line utility that exposes 
+`WmlComparer's` redlining capabilities. We are currently target win-x64 and linux-x64 builds, but any runtime
+[supported by .NET](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) is theoretically supported. 
+
+**Our build script does the following:**
+
+1. Build a binary for Linux:
+
+```bash
+dotnet publish -c Release -r linux-x64 --self-contained
+```
+
+2. Build a binary for Windows:
+
+```bash
+dotnet publish -c Release -r win-x64 --self-contained
+```
+
+3. Archive and package binaries into `./dist/`:
+
+
+## Running Tests
+
+To ensure everything is set up correctly and working as expected, run the tests included in the `tests/` directory.
+
+### Step 1: Navigate to the Test Directory
+
+Change to the `tests/` directory in your project:
+
+```bash
+cd path/to/tests
+```
+
+### Step 2: Run the Tests
+
+Execute the tests using pytest:
+
+```bash
+pytest
+```
+
+This will run all the test cases defined in your test files.
+
+## Conclusion
+
+You've now set up the RedlinesWrapper project, built the necessary C# binaries, and learned how to use the Python wrapper to compare `.docx` files. Running the tests ensures that your setup is correct and the wrapper functions as expected.
+
+---
+
+Feel free to modify this Quickstart Guide to better fit the specifics of your project, such as the exact commands for building the C# binaries or the directory structure of your project. This guide provides a general framework to get users started with the RedlinesWrapper.

docs/developer-guide.md

@@ -0,0 +1,43 @@
+# Python-Redlines Quickstart
+
+As discussed in the main README, the initial version is a wrapper for the C# api provided by Open-XML-PowerTools and
+`WmlComparer`. This readme will show you how to use the XmlPowerToolsEngine to run a redline. 
+
+### 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
+
+wrapper = XmlPowerToolsEngine()
+```
+
+### Step 2: Run Redlines
+
+Use the `run_redlines` method to compare documents. You can pass the paths of the `.docx` files or their byte content:
+
+```python
+# Example with file paths
+output = wrapper.run_redlines('AuthorTag', '/path/to/original.docx', '/path/to/modified.docx')
+
+# Example with byte content
+with open('/path/to/original.docx', 'rb') as f:
+    original_bytes = f.read()
+with open('/path/to/modified.docx', 'rb') as f:
+    modified_bytes = f.read()
+
+output = wrapper.run_redlines('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.
+
+### Step 3: Handle the Output
+
+Process or save the output as needed. For example, to save the redline output to a file:
+
+```python
+with open('/path/to/redline_output.docx', 'wb') as f:
+    f.write(output)
+```

docs/quickstart.md

@@ -0,0 +1 @@
+*

src/python_redlines/bin/.gitignore

@@ -0,0 +1 @@
+!*