Skip to content

Commit df1326b

Browse files
wolfieschwolfiesch
committed
docs(pyumya): add guides and improve mkdocs navigation
1 parent 39fdfe9 commit df1326b

8 files changed

Lines changed: 461 additions & 7 deletions

File tree

‎docs/pyumya/docs/guides/comments.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Comments
2+
3+
Add, read, and manage cell comments (notes) in Excel workbooks.
4+
5+
## Reading Comments
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("annotated.xlsx")
11+
comments = book.read_comments("Sheet1")
12+
for c in comments:
13+
print(f"{c['cell']}: {c['text']} (by {c['author']})")
14+
# A1: Review this value (by John)
15+
# B3: Updated 2026-01-15 (by Jane)
16+
```
17+
18+
## Writing Comments
19+
20+
```python
21+
book = UmyaBook()
22+
book.add_sheet("Data")
23+
24+
book.write_cell_value("Data", "A1", {"type": "number", "value": 42.0})
25+
book.add_comment("Data", "A1", {
26+
"text": "This value needs verification",
27+
"author": "Reviewer",
28+
})
29+
30+
book.save("output.xlsx")
31+
```
32+
33+
## How Comments Appear in Excel
34+
35+
!!! tip
36+
Comments appear as hover tooltips in Excel. A small red triangle in the
37+
cell corner indicates a comment is present. In newer versions of Excel,
38+
these are called "Notes" (threaded "Comments" are a separate feature
39+
that pyumya does not currently support).
40+
41+
## Best Practices
42+
43+
- Keep comment text concise — long comments are hard to read in the tooltip
44+
- Include dates in comments for audit trails
45+
- Use the `author` field consistently across your organization

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

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Conditional Formatting
2+
3+
Apply formatting rules that change cell appearance based on values.
4+
5+
## Reading Conditional Formats
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("dashboard.xlsx")
11+
rules = book.read_conditional_formats("Sheet1")
12+
for r in rules:
13+
print(f"{r['ranges']}: {r['type']}")
14+
# ['A1:A100']: cellIs
15+
# ['B1:B100']: colorScale
16+
```
17+
18+
## Writing Conditional Formats
19+
20+
### Cell Value Rules
21+
22+
```python
23+
book = UmyaBook()
24+
book.add_sheet("Sales")
25+
26+
# Highlight cells greater than 1000
27+
book.add_conditional_format("Sales", {
28+
"ranges": ["B2:B50"],
29+
"type": "cellIs",
30+
"operator": "greaterThan",
31+
"formula": "1000",
32+
"format": {"bg_color": "#C6EFCE", "font_color": "#006100"}, # green
33+
})
34+
35+
# Highlight cells below target
36+
book.add_conditional_format("Sales", {
37+
"ranges": ["B2:B50"],
38+
"type": "cellIs",
39+
"operator": "lessThan",
40+
"formula": "500",
41+
"format": {"bg_color": "#FFC7CE", "font_color": "#9C0006"}, # red
42+
})
43+
44+
book.save("output.xlsx")
45+
```
46+
47+
### Color Scales
48+
49+
```python
50+
# 2-color scale (red to green)
51+
book.add_conditional_format("Sales", {
52+
"ranges": ["C2:C50"],
53+
"type": "colorScale",
54+
"color_scale": {
55+
"min_color": "#FF0000",
56+
"max_color": "#00FF00",
57+
},
58+
})
59+
60+
# 3-color scale (red / yellow / green)
61+
book.add_conditional_format("Sales", {
62+
"ranges": ["D2:D50"],
63+
"type": "colorScale",
64+
"color_scale": {
65+
"min_color": "#FF0000",
66+
"mid_color": "#FFFF00",
67+
"max_color": "#00FF00",
68+
},
69+
})
70+
```
71+
72+
### Data Bars
73+
74+
```python
75+
book.add_conditional_format("Sales", {
76+
"ranges": ["E2:E50"],
77+
"type": "dataBar",
78+
"data_bar": {"color": "#638EC6"},
79+
})
80+
```
81+
82+
## Rule Types
83+
84+
| Type | Description | Key fields |
85+
|------|-------------|-----------|
86+
| `cellIs` | Compare cell value | `operator`, `formula`, `format` |
87+
| `colorScale` | Gradient fill | `color_scale` with 2-3 colors |
88+
| `dataBar` | In-cell bar chart | `data_bar` with color |
89+
| `top10` | Top/bottom N | `rank`, `percent`, `bottom` |
90+
| `containsText` | Text matching | `text`, `format` |
91+
92+
## Rule Priority
93+
94+
!!! info "Evaluation order"
95+
When multiple rules apply to the same cell, rules are evaluated
96+
in the order they were added. The first matching rule determines
97+
the formatting. This matches Excel's "Stop if True" default behavior.

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Data Validation
2+
3+
Add dropdown lists, input constraints, and validation rules to cells.
4+
5+
## Reading Validations
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("form.xlsx")
11+
validations = book.read_data_validations("Sheet1")
12+
for v in validations:
13+
print(f"{v['ranges']}: {v['type']} — {v.get('formula1', '')}")
14+
# ['B2:B100']: list — "Option A,Option B,Option C"
15+
# ['C2:C100']: whole — 1
16+
```
17+
18+
## Writing Validations
19+
20+
### Dropdown List
21+
22+
```python
23+
book = UmyaBook()
24+
book.add_sheet("Form")
25+
26+
# Create a dropdown list
27+
book.add_data_validation("Form", {
28+
"ranges": ["B2:B100"],
29+
"type": "list",
30+
"formula1": "Option A,Option B,Option C",
31+
"show_dropdown": True,
32+
})
33+
34+
book.save("output.xlsx")
35+
```
36+
37+
### Numeric Constraints
38+
39+
```python
40+
# Whole number between 1 and 100
41+
book.add_data_validation("Form", {
42+
"ranges": ["C2:C50"],
43+
"type": "whole",
44+
"operator": "between",
45+
"formula1": "1",
46+
"formula2": "100",
47+
"error_title": "Invalid Input",
48+
"error_message": "Enter a number between 1 and 100",
49+
})
50+
```
51+
52+
### Date Range
53+
54+
```python
55+
# Dates in 2026 only
56+
book.add_data_validation("Form", {
57+
"ranges": ["D2:D50"],
58+
"type": "date",
59+
"operator": "between",
60+
"formula1": "2026-01-01",
61+
"formula2": "2026-12-31",
62+
})
63+
```
64+
65+
## Validation Types
66+
67+
| Type | Description | Example |
68+
|------|-------------|---------|
69+
| `list` | Dropdown selection | `"Red,Green,Blue"` |
70+
| `whole` | Integer constraint | Between 1 and 100 |
71+
| `decimal` | Float constraint | Greater than 0.0 |
72+
| `date` | Date constraint | After 2026-01-01 |
73+
| `textLength` | String length | Max 50 characters |
74+
| `custom` | Custom formula | `=AND(A1>0, A1<100)` |
75+
76+
## Operators
77+
78+
`between`, `notBetween`, `equal`, `notEqual`, `greaterThan`,
79+
`lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`.

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

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Freeze Panes
2+
3+
Lock rows and columns so they stay visible while scrolling.
4+
5+
## Reading Freeze Pane Settings
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("dashboard.xlsx")
11+
panes = book.read_freeze_panes("Sheet1")
12+
print(panes) # {"row": 1, "column": 0} (top row frozen)
13+
```
14+
15+
## Writing Freeze Panes
16+
17+
```python
18+
book = UmyaBook()
19+
book.add_sheet("Data")
20+
21+
# Freeze top row (headers stay visible)
22+
book.set_freeze_panes("Data", {"row": 1, "column": 0})
23+
24+
# Freeze first column
25+
book.set_freeze_panes("Data", {"row": 0, "column": 1})
26+
27+
# Freeze both (top-left corner stays fixed)
28+
book.set_freeze_panes("Data", {"row": 1, "column": 1})
29+
30+
book.save("output.xlsx")
31+
```
32+
33+
## Common Patterns
34+
35+
| Use case | Settings | Excel equivalent |
36+
|----------|----------|-----------------|
37+
| Header row | `{"row": 1, "column": 0}` | View > Freeze Top Row |
38+
| First column | `{"row": 0, "column": 1}` | View > Freeze First Column |
39+
| Both | `{"row": 1, "column": 1}` | Select B2 > Freeze Panes |
40+
| Multi-row header | `{"row": 3, "column": 0}` | Select A4 > Freeze Panes |
41+
42+
!!! tip
43+
The `row` and `column` values specify the **split position** — rows above
44+
and columns to the left of that position are frozen. This matches the
45+
cell you'd select in Excel before clicking "Freeze Panes."

‎docs/pyumya/docs/guides/hyperlinks.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Hyperlinks
2+
3+
Add and read hyperlinks in Excel cells.
4+
5+
## Reading Hyperlinks
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("links.xlsx")
11+
links = book.read_hyperlinks("Sheet1")
12+
for link in links:
13+
print(f"{link['cell']}: {link['target']} ({link.get('display', '')})")
14+
# A1: https://example.com (Example Site)
15+
# B2: mailto:user@example.com (Contact Us)
16+
```
17+
18+
## Writing Hyperlinks
19+
20+
```python
21+
book = UmyaBook()
22+
book.add_sheet("Links")
23+
24+
# Web URL
25+
book.write_cell_value("Links", "A1", {"type": "string", "value": "Visit Example"})
26+
book.add_hyperlink("Links", "A1", {
27+
"target": "https://example.com",
28+
"display": "Visit Example",
29+
})
30+
31+
# Email link
32+
book.add_hyperlink("Links", "A2", {
33+
"target": "mailto:support@example.com",
34+
"display": "Email Support",
35+
})
36+
37+
# Internal reference (another sheet)
38+
book.add_hyperlink("Links", "A3", {
39+
"target": "#Summary!A1",
40+
"display": "Go to Summary",
41+
})
42+
43+
book.save("output.xlsx")
44+
```
45+
46+
## Hyperlink Types
47+
48+
| Type | Target format | Example |
49+
|------|--------------|---------|
50+
| Web URL | `https://...` | `https://example.com` |
51+
| Email | `mailto:...` | `mailto:user@example.com` |
52+
| Internal | `#SheetName!Cell` | `#Summary!A1` |
53+
| File | Relative or absolute path | `../other.xlsx` |
54+
55+
## Styling
56+
57+
!!! note
58+
Excel automatically applies blue underline formatting to hyperlinked cells.
59+
pyumya does not auto-apply this styling — if you want the visual cue,
60+
apply font formatting separately.

‎docs/pyumya/docs/guides/images.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Images
2+
3+
Embed and read images in Excel worksheets.
4+
5+
## Reading Images
6+
7+
```python
8+
from excelbench_rust import UmyaBook
9+
10+
book = UmyaBook.open("report.xlsx")
11+
images = book.read_images("Sheet1")
12+
for img in images:
13+
print(f"Cell {img['cell']}: {img['format']} ({len(img['data'])} bytes)")
14+
# Cell A1: png (24576 bytes)
15+
```
16+
17+
## Writing Images
18+
19+
```python
20+
from pathlib import Path
21+
from excelbench_rust import UmyaBook
22+
23+
book = UmyaBook()
24+
book.add_sheet("Report")
25+
26+
# Embed an image from file
27+
book.add_image("Report", "B2", {
28+
"data": Path("logo.png").read_bytes(),
29+
"format": "png",
30+
})
31+
32+
book.save("output.xlsx")
33+
```
34+
35+
## Supported Formats
36+
37+
| Format | Extension | Read | Write |
38+
|--------|-----------|:----:|:-----:|
39+
| PNG | `.png` | Yes | Yes |
40+
| JPEG | `.jpg`, `.jpeg` | Yes | Yes |
41+
| GIF | `.gif` | Yes | Yes |
42+
| BMP | `.bmp` | Yes | Yes |
43+
| EMF | `.emf` | Yes | Yes |
44+
45+
## Image Positioning
46+
47+
!!! note "Anchor behavior"
48+
Images are anchored to a cell position. When rows/columns are
49+
resized, the image moves with its anchor cell. The image size
50+
is determined by the original image dimensions — pyumya does
51+
not currently support explicit width/height overrides.
52+
53+
## Best Practices
54+
55+
- Use PNG for logos and diagrams (lossless, supports transparency)
56+
- Use JPEG for photographs (smaller file size)
57+
- Keep images under 1 MB for reasonable workbook file sizes
58+
- Place images in dedicated "cover" or "chart" sheets to avoid layout issues

0 commit comments

Comments
 (0)