docs(pyumya): fix guide examples to match UmyaBook API

Author: wolfiesch

docs/pyumya/docs/guides/comments.md

@@ -18,11 +18,14 @@ for c in comments:
 ## Writing Comments
 
 ```python
+from excelbench_rust import UmyaBook
+
 book = UmyaBook()
 book.add_sheet("Data")
 
 book.write_cell_value("Data", "A1", {"type": "number", "value": 42.0})
-book.add_comment("Data", "A1", {
+book.add_comment("Data", {
+    "cell": "A1",
     "text": "This value needs verification",
     "author": "Reviewer",
 })

docs/pyumya/docs/guides/conditional-formatting.md

@@ -10,32 +10,32 @@ from excelbench_rust import UmyaBook
 book = UmyaBook.open("dashboard.xlsx")
 rules = book.read_conditional_formats("Sheet1")
 for r in rules:
-    print(f"{r['ranges']}: {r['type']}")
-# ['A1:A100']: cellIs
-# ['B1:B100']: colorScale
+    print(f"{r['range']}: {r['rule_type']}")
+# A1:A100: cellIs
+# B1:B100: colorScale
 ```
 
 ## Writing Conditional Formats
 
-### Cell Value Rules
-
 ```python
+from excelbench_rust import UmyaBook
+
 book = UmyaBook()
 book.add_sheet("Sales")
 
 # Highlight cells greater than 1000
 book.add_conditional_format("Sales", {
-    "ranges": ["B2:B50"],
-    "type": "cellIs",
+    "range": "B2:B50",
+    "rule_type": "cellIs",
     "operator": "greaterThan",
     "formula": "1000",
     "format": {"bg_color": "#C6EFCE", "font_color": "#006100"},  # green
 })
 
 # Highlight cells below target
 book.add_conditional_format("Sales", {
-    "ranges": ["B2:B50"],
-    "type": "cellIs",
+    "range": "B2:B50",
+    "rule_type": "cellIs",
     "operator": "lessThan",
     "formula": "500",
     "format": {"bg_color": "#FFC7CE", "font_color": "#9C0006"},  # red
@@ -44,54 +44,12 @@ book.add_conditional_format("Sales", {
 book.save("output.xlsx")
 ```
 
-### Color Scales
-
-```python
-# 2-color scale (red to green)
-book.add_conditional_format("Sales", {
-    "ranges": ["C2:C50"],
-    "type": "colorScale",
-    "color_scale": {
-        "min_color": "#FF0000",
-        "max_color": "#00FF00",
-    },
-})
-
-# 3-color scale (red / yellow / green)
-book.add_conditional_format("Sales", {
-    "ranges": ["D2:D50"],
-    "type": "colorScale",
-    "color_scale": {
-        "min_color": "#FF0000",
-        "mid_color": "#FFFF00",
-        "max_color": "#00FF00",
-    },
-})
-```
-
-### Data Bars
-
-```python
-book.add_conditional_format("Sales", {
-    "ranges": ["E2:E50"],
-    "type": "dataBar",
-    "data_bar": {"color": "#638EC6"},
-})
-```
-
 ## Rule Types
 
-| Type | Description | Key fields |
+| Type | Description | Notes |
 |------|-------------|-----------|
-| `cellIs` | Compare cell value | `operator`, `formula`, `format` |
-| `colorScale` | Gradient fill | `color_scale` with 2-3 colors |
-| `dataBar` | In-cell bar chart | `data_bar` with color |
-| `top10` | Top/bottom N | `rank`, `percent`, `bottom` |
-| `containsText` | Text matching | `text`, `format` |
-
-## Rule Priority
-
-!!! info "Evaluation order"
-    When multiple rules apply to the same cell, rules are evaluated
-    in the order they were added. The first matching rule determines
-    the formatting. This matches Excel's "Stop if True" default behavior.
+| `cellIs` | Compare cell value | Writing supported (operator/formula + basic colors) |
+| `expression` | Formula-based condition | Writing supported (formula + basic colors) |
+| `colorScale` | Gradient fill | Currently read-only in the Python API |
+| `dataBar` | In-cell bar chart | Currently read-only in the Python API |
+| `iconSet` | Icon set | Currently read-only in the Python API |

docs/pyumya/docs/guides/data-validation.md

@@ -10,56 +10,48 @@ from excelbench_rust import UmyaBook
 book = UmyaBook.open("form.xlsx")
 validations = book.read_data_validations("Sheet1")
 for v in validations:
-    print(f"{v['ranges']}: {v['type']} — {v.get('formula1', '')}")
-# ['B2:B100']: list — "Option A,Option B,Option C"
-# ['C2:C100']: whole — 1
+    print(f"{v['range']}: {v['validation_type']} — {v.get('formula1')}")
+# B2:B100: list — Option A,Option B,Option C
+# C2:C100: whole — 1
 ```
 
 ## Writing Validations
 
-### Dropdown List
-
 ```python
+from excelbench_rust import UmyaBook
+
 book = UmyaBook()
 book.add_sheet("Form")
 
-# Create a dropdown list
 book.add_data_validation("Form", {
-    "ranges": ["B2:B100"],
-    "type": "list",
+    "range": "B2:B100",
+    "validation_type": "list",
     "formula1": "Option A,Option B,Option C",
-    "show_dropdown": True,
+    "allow_blank": True,
 })
 
-book.save("output.xlsx")
-```
-
-### Numeric Constraints
-
-```python
 # Whole number between 1 and 100
 book.add_data_validation("Form", {
-    "ranges": ["C2:C50"],
-    "type": "whole",
+    "range": "C2:C50",
+    "validation_type": "whole",
     "operator": "between",
     "formula1": "1",
     "formula2": "100",
     "error_title": "Invalid Input",
-    "error_message": "Enter a number between 1 and 100",
+    "error": "Enter a number between 1 and 100",
+    "show_error": True,
 })
-```
-
-### Date Range
 
-```python
 # Dates in 2026 only
 book.add_data_validation("Form", {
-    "ranges": ["D2:D50"],
-    "type": "date",
+    "range": "D2:D50",
+    "validation_type": "date",
     "operator": "between",
     "formula1": "2026-01-01",
     "formula2": "2026-12-31",
 })
+
+book.save("output.xlsx")
 ```
 
 ## Validation Types

docs/pyumya/docs/guides/freeze-panes.md

@@ -9,23 +9,29 @@ from excelbench_rust import UmyaBook
 
 book = UmyaBook.open("dashboard.xlsx")
 panes = book.read_freeze_panes("Sheet1")
-print(panes)  # {"row": 1, "column": 0}  (top row frozen)
+print(panes)  # {"mode": "freeze", "top_left_cell": "A2"}  (top row frozen)
 ```
 
 ## Writing Freeze Panes
 
 ```python
+from excelbench_rust import UmyaBook
+
 book = UmyaBook()
 book.add_sheet("Data")
 
-# Freeze top row (headers stay visible)
-book.set_freeze_panes("Data", {"row": 1, "column": 0})
+# Freeze panes are configured via:
+# - mode: "freeze" | "split"
+# - top_left_cell: e.g. "B2" (the first scrollable cell)
+
+# To freeze the top row (headers stay visible):
+# book.set_freeze_panes("Data", {"mode": "freeze", "top_left_cell": "A2"})
 
-# Freeze first column
-book.set_freeze_panes("Data", {"row": 0, "column": 1})
+# To freeze the first column:
+# book.set_freeze_panes("Data", {"mode": "freeze", "top_left_cell": "B1"})
 
-# Freeze both (top-left corner stays fixed)
-book.set_freeze_panes("Data", {"row": 1, "column": 1})
+# To freeze both top row + first column:
+book.set_freeze_panes("Data", {"mode": "freeze", "top_left_cell": "B2"})
 
 book.save("output.xlsx")
 ```
@@ -34,12 +40,12 @@ book.save("output.xlsx")
 
 | Use case | Settings | Excel equivalent |
 |----------|----------|-----------------|
-| Header row | `{"row": 1, "column": 0}` | View > Freeze Top Row |
-| First column | `{"row": 0, "column": 1}` | View > Freeze First Column |
-| Both | `{"row": 1, "column": 1}` | Select B2 > Freeze Panes |
-| Multi-row header | `{"row": 3, "column": 0}` | Select A4 > Freeze Panes |
+| Header row | `{"mode": "freeze", "top_left_cell": "A2"}` | View > Freeze Top Row |
+| First column | `{"mode": "freeze", "top_left_cell": "B1"}` | View > Freeze First Column |
+| Both | `{"mode": "freeze", "top_left_cell": "B2"}` | Select B2 > Freeze Panes |
+| Multi-row header | `{"mode": "freeze", "top_left_cell": "A4"}` | Select A4 > Freeze Panes |
 
 !!! tip
-    The `row` and `column` values specify the **split position** — rows above
-    and columns to the left of that position are frozen. This matches the
-    cell you'd select in Excel before clicking "Freeze Panes."
+    `top_left_cell` is the first scrollable cell. Rows above and columns to
+    the left of that cell become frozen. This matches the cell you'd select
+    in Excel before clicking "Freeze Panes."

docs/pyumya/docs/guides/hyperlinks.md

@@ -18,26 +18,31 @@ for link in links:
 ## Writing Hyperlinks
 
 ```python
+from excelbench_rust import UmyaBook
+
 book = UmyaBook()
 book.add_sheet("Links")
 
 # Web URL
-book.write_cell_value("Links", "A1", {"type": "string", "value": "Visit Example"})
-book.add_hyperlink("Links", "A1", {
+book.add_hyperlink("Links", {
+    "cell": "A1",
     "target": "https://example.com",
     "display": "Visit Example",
 })
 
 # Email link
-book.add_hyperlink("Links", "A2", {
+book.add_hyperlink("Links", {
+    "cell": "A2",
     "target": "mailto:support@example.com",
     "display": "Email Support",
 })
 
 # Internal reference (another sheet)
-book.add_hyperlink("Links", "A3", {
+book.add_hyperlink("Links", {
+    "cell": "A3",
     "target": "#Summary!A1",
     "display": "Go to Summary",
+    "internal": True,
 })
 
 book.save("output.xlsx")

docs/pyumya/docs/guides/images.md

@@ -10,37 +10,32 @@ from excelbench_rust import UmyaBook
 book = UmyaBook.open("report.xlsx")
 images = book.read_images("Sheet1")
 for img in images:
-    print(f"Cell {img['cell']}: {img['format']} ({len(img['data'])} bytes)")
-# Cell A1: png (24576 bytes)
+    print(f"Image at {img['cell']}: anchor={img['anchor']}, offset={img['offset']}")
+# Image at A1: anchor=oneCell, offset=[0, 0]
 ```
 
 ## Writing Images
 
 ```python
-from pathlib import Path
 from excelbench_rust import UmyaBook
 
 book = UmyaBook()
 book.add_sheet("Report")
 
-# Embed an image from file
-book.add_image("Report", "B2", {
-    "data": Path("logo.png").read_bytes(),
-    "format": "png",
+# Embed an image by file path
+book.add_image("Report", {
+    "path": "logo.png",
+    "cell": "B2",
 })
 
 book.save("output.xlsx")
 ```
 
-## Supported Formats
+## Formats
 
-| Format | Extension | Read | Write |
-|--------|-----------|:----:|:-----:|
-| PNG | `.png` | Yes | Yes |
-| JPEG | `.jpg`, `.jpeg` | Yes | Yes |
-| GIF | `.gif` | Yes | Yes |
-| BMP | `.bmp` | Yes | Yes |
-| EMF | `.emf` | Yes | Yes |
+The Python API currently exposes image **anchors** (positioning) but does not
+expose image bytes or a detected format on read. For writes, provide a file
+path (e.g. PNG/JPEG).
 
 ## Image Positioning
 

docs/pyumya/docs/guides/merged-cells.md

@@ -1,14 +1,14 @@
 # Merged Cells
 
-Merge and unmerge cell ranges in Excel workbooks.
+Merge cell ranges in Excel workbooks.
 
 ## Reading Merged Ranges
 
 ```python
 from excelbench_rust import UmyaBook
 
 book = UmyaBook.open("report.xlsx")
-merged = book.read_merged_cells("Sheet1")
+merged = book.read_merged_ranges("Sheet1")
 print(merged)  # ["A1:D1", "B3:B5"]
 ```
 
@@ -40,3 +40,8 @@ book.save("output.xlsx")
 - Merging a range that overlaps an existing merge will raise an error in Excel
 - Single-cell "merges" (e.g., `"A1:A1"`) are valid but have no visual effect
 - Merged cells with borders apply the border to the entire merged region
+
+!!! note "Unmerge"
+    Unmerging is not currently exposed in the Python API. If you need it, open
+    an issue and include the exact Excel behavior you want (preserve top-left
+    value, how to handle formatting, etc.).

docs/pyumya/mkdocs.yml

@@ -65,8 +65,6 @@ extra:
 
 nav:
   - Home: index.md
-  - Getting Started:
-      - Installation: index.md
   - Guides:
       - Merged Cells: guides/merged-cells.md
       - Comments: guides/comments.md