update docs wip

Author: EgeKaraismailogluQC

docs/api/diffly.cli.rst

@@ -0,0 +1,7 @@
+diffly.cli module
+=================
+
+.. automodule:: diffly.cli
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/diffly.comparison.rst

@@ -0,0 +1,7 @@
+diffly.comparison module
+========================
+
+.. automodule:: diffly.comparison
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/diffly.rst

@@ -0,0 +1,21 @@
+diffly package
+==============
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   diffly.cli
+   diffly.comparison
+   diffly.summary
+   diffly.testing
+
+Module contents
+---------------
+
+.. automodule:: diffly
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/diffly.summary.rst

@@ -0,0 +1,7 @@
+diffly.summary module
+=====================
+
+.. automodule:: diffly.summary
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/diffly.testing.rst

@@ -0,0 +1,7 @@
+diffly.testing module
+=====================
+
+.. automodule:: diffly.testing
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/api/modules.rst

@@ -0,0 +1,7 @@
+diffly
+======
+
+.. toctree::
+   :maxdepth: 4
+
+   diffly

docs/conf.py

@@ -40,6 +40,8 @@
     "numpydoc",
     "sphinx.ext.linkcode",
     "sphinxcontrib.apidoc",
+    "myst_parser",
+    "sphinx_copybutton",
 ]
 
 apidoc_module_dir = "../diffly"
@@ -49,9 +51,29 @@
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+pygments_style = "lovelace"
+html_theme_options = {
+    "external_links": [],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/Quantco/diffly",
+            "icon": "fa-brands fa-github",
+        },
+    ],
+}
+html_title = "Diffly"
 html_static_path = ["_static"]
 
+# object signatures
+maximum_signature_line_length = 88
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
 
 # Copied and adapted from
 # https://github.com/pandas-dev/pandas/blob/4a14d064187367cacab3ff4652a12a0e45d0711b/doc/source/conf.py#L613-L659

docs/guides/index.md

@@ -0,0 +1,20 @@
+# User Guide
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+quickstart
+examples/index
+features/index
+faq
+```
+
+## Installation
+
+To install `diffly`, use your favorite package manager, e.g., using `pixi` or `pip`:
+
+```bash
+pixi add diffly
+pip install diffly
+```

docs/index.md

@@ -0,0 +1,70 @@
+# Diffly
+
+A utility package for comparing Polars DataFrames.
+
+```{toctree}
+:maxdepth: 2
+:hidden:
+
+guides/index
+API Reference <api/modules>
+```
+
+## What is Diffly?
+
+Diffly is a utility package for comparing Polars DataFrames and LazyFrames with detailed analysis capabilities. It identifies differences between datasets including:
+
+- **Schema differences**: Columns that exist only in one DataFrame
+- **Row-level mismatches**: Rows that are different between DataFrames
+- **Missing rows**: Rows that exist only in one DataFrame
+- **Column value changes**: Detailed analysis of which columns differ and by how much
+
+## Key Features
+
+- **Primary key-based comparison**: Join DataFrames on specified primary keys for row-by-row comparison
+- **Tolerance-based equality**: Configure absolute and relative tolerances for floating point comparisons
+- **Temporal tolerance**: Support for comparing temporal types (dates, datetimes) with configurable tolerances
+- **Rich summaries**: Generate detailed, visually formatted comparison reports
+- **Lazy evaluation**: Uses Polars LazyFrames internally for efficient computation
+- **Method caching**: Automatically caches comparison results to avoid recomputation
+- **Per-column tolerances**: Fine-grained control over comparison tolerances for each column
+- **Testing utilities**: Built-in assertion functions for DataFrame and Collection equality in tests
+
+## Quick Example
+
+```python
+import polars as pl
+from diffly import compare_frames
+
+# Create two DataFrames to compare
+left = pl.DataFrame({
+    "id": ["a", "b", "c"],
+    "value": [1.0, 2.0, 3.0],
+    "category": ["x", "y", "z"]
+})
+
+right = pl.DataFrame({
+    "id": ["a", "b", "d"],
+    "value": [1.0, 2.1, 4.0],
+    "category": ["x", "y", "w"]
+})
+
+# Compare the DataFrames
+comparison = compare_frames(left, right, primary_key="id")
+
+# Check if they're equal
+if not comparison.equal():
+    # Display a detailed summary
+    summary = comparison.summary(
+        show_perfect_column_matches=True,
+        top_k_column_changes=5
+    )
+    print(summary)
+```
+
+## Next Steps
+
+- Follow the [Quickstart Guide](guides/quickstart.md) for a comprehensive introduction
+- Explore [Examples](guides/examples/index.md) for common use cases
+- Learn about advanced [Features](guides/features/index.md) like tolerances and custom summaries
+- Check the [API Reference](api/modules.rst) for detailed function documentation