{feat} Documentation optimisations

Author: alex-rowley

CLAUDE.md

@@ -0,0 +1,181 @@
+# CLAUDE.md
+
+This file provides guidance for Claude Code (and human developers) working with the py-svg-chart codebase.
+
+## Project Overview
+
+**py-svg-chart** is a Python library for generating SVG charts entirely in Python. It produces clean, standalone SVG output that can be embedded directly in web applications without JavaScript dependencies or post-processing.
+
+**Key differentiator:** Unlike image-based charting libraries or JS-dependent solutions, this generates resolution-independent, customizable SVG markup server-side.
+
+## Quick Start
+
+```bash
+pip install pysvgchart
+```
+
+```python
+import pysvgchart as psc
+
+# Simple donut chart
+chart = psc.DonutChart([25, 30, 20, 25])
+svg = chart.render()
+
+# Line chart
+chart = psc.SimpleLineChart(
+    x_values=[1, 2, 3, 4, 5],
+    y_values=[[10, 20, 15, 25, 30]],
+    y_names=['Sales']
+)
+chart.add_legend()
+svg = chart.render()
+```
+
+## Architecture Overview
+
+```
+pysvgchart/
+├── charts.py      # Chart classes (entry points for users)
+├── axes.py        # Axis management (XAxis, YAxis, CategoryYAxis)
+├── series.py      # Data series (LineSeries, BarSeries, ScatterSeries, DonutSegment)
+├── scales.py      # Scale calculations (Linear, Logarithmic, Categorical)
+├── legends.py     # Legend rendering
+├── shapes.py      # SVG primitives (Point, Line, Circle, Rect, Text, Group)
+├── helpers.py     # Utility functions (tick generation, formatting)
+├── styles.py      # CSS style rendering for hover effects
+└── shared.py      # Type definitions
+```
+
+### Class Hierarchy
+
+```
+Chart (ABC)
+├── CartesianChart
+│   ├── VerticalChart        # Y-axis vertical, X-axis horizontal
+│   │   ├── LineChart        # Line/area charts
+│   │   │   ├── SimpleLineChart
+│   │   │   ├── BarChart
+│   │   │   ├── NormalisedBarChart
+│   │   │   └── ScatterChart
+│   │   └── (inherits axis setup)
+│   └── HorizontalChart      # X-axis has values, Y-axis has categories
+│       └── HorizontalBarChart
+└── DonutChart               # Pie/donut (non-Cartesian)
+```
+
+### Data Flow
+
+1. **User creates chart** with x_values, y_values, configuration
+2. **Axes created** via `x_axis_type`/`y_axis_type` using `scale_maker` functions
+3. **Series constructed** via `series_constructor` (converts data to positioned shapes)
+4. **Optional additions:** legends, grids, hover modifiers, custom elements
+5. **Render:** `chart.render()` or `chart.render_with_all_styles()` produces SVG string
+
+### Key Design Patterns
+
+- **Factory Pattern:** `series_constructor` functions create appropriate Series types
+- **Template Method:** Base `Chart` defines `render()`, subclasses implement `get_element_list()`
+- **Strategy Pattern:** Pluggable `scale_maker` functions, `label_format` callbacks
+- **Composition:** Charts compose axes, series, legends, shapes
+
+## Chart Types
+
+| Chart | Class | Use Case |
+|-------|-------|----------|
+| Line | `LineChart`, `SimpleLineChart` | Time series, trends |
+| Bar (vertical) | `BarChart` | Category comparisons |
+| Bar (horizontal) | `HorizontalBarChart` | Long category names |
+| Stacked (100%) | `NormalisedBarChart` | Part-of-whole comparisons |
+| Scatter | `ScatterChart` | Correlation, distribution |
+| Donut/Pie | `DonutChart` | Proportions |
+
+## Common Patterns
+
+### Adding Interactivity (Hover Effects)
+
+```python
+def hover_fn(position, x_value, y_value, series_name, styles):
+    return [psc.Text(x=position.x, y=position.y-10, content=str(y_value),
+                     classes=['psc-hover-data'])]
+
+chart.add_hover_modifier(hover_fn, radius=5)
+svg = chart.render_with_all_styles()  # Must use this for hovers
+```
+
+### Custom Styling
+
+```python
+# Direct series style modification
+chart.series['Series Name'].styles = {'stroke': 'red', 'stroke-width': '3'}
+
+# Access axis elements
+chart.x_axis.tick_lines = []  # Remove tick marks
+chart.y_axis.axis_line.styles['stroke'] = '#ccc'
+```
+
+### Adding Custom Elements
+
+```python
+chart.add_custom_element(psc.Circle(x=100, y=100, radius=5, styles={'fill': 'red'}))
+chart.add_custom_element(psc.Text(x=200, y=50, content='Annotation'))
+```
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_pysvgchart.py
+
+# Tests generate SVG files in showcase/ directory
+```
+
+The `showcase/` directory contains generated SVG examples from the test suite.
+
+## File Purposes
+
+| File | Purpose |
+|------|---------|
+| `charts.py` | Main entry points. All public chart classes. Series constructors. |
+| `axes.py` | Axis rendering, tick generation, scale positioning |
+| `series.py` | Data series types that render as SVG paths/shapes |
+| `scales.py` | Numeric scale calculations (min/max, tick intervals) |
+| `shapes.py` | Low-level SVG elements (Point, Line, Circle, Text, Group) |
+| `legends.py` | Legend components for each chart type |
+| `helpers.py` | Utility functions (formatting, element list flattening) |
+| `styles.py` | CSS generation for hover effects |
+| `shared.py` | Type aliases used across modules |
+
+## Type System
+
+Key type aliases from `shared.py`:
+- `number = float | int`
+- `numbers_sequence = list[number] | tuple[number, ...]`
+- `style_def = dict[str, str]` (SVG style attributes)
+
+## Common Tasks
+
+### Adding a new chart type
+
+1. Choose base class (`VerticalChart`, `HorizontalChart`, or `Chart`)
+2. Set class attributes: `x_axis_type`, `y_axis_type`, `series_constructor`, `scale_maker`s
+3. Override `add_legend()` if needed
+4. Add to `__init__.py` exports
+
+### Modifying axis behavior
+
+Axes are in `axes.py`. Key methods:
+- `get_positions()` - Convert data values to pixel positions
+- Scale creation via `scale_maker` parameter
+
+### Adding new shapes
+
+Add to `shapes.py`. Inherit from `Element` or `Shape`, implement `get_element_list()` to return SVG strings.
+
+## Dependencies
+
+- Python 3.10+
+- No runtime dependencies (standard library only)
+- Dev: pytest for testing

pysvgchart/__init__.py

@@ -1,4 +1,36 @@
-"""Top-level package for py-svg-chart"""
+"""
+pysvgchart - Python SVG Chart Generator
+
+Generate clean, standalone SVG charts in Python for embedding in web applications.
+
+Chart Types:
+    LineChart, SimpleLineChart - Line plots for time series and trends
+    BarChart - Vertical bar charts for category comparisons
+    HorizontalBarChart - Horizontal bars (useful for long category names)
+    NormalisedBarChart - 100% stacked bars for part-of-whole comparisons
+    ScatterChart - Scatter plots for correlation/distribution
+    DonutChart - Pie/donut charts for proportions
+
+Shape Primitives (for custom elements):
+    Circle, Line, Text
+
+Styling:
+    hover_style_name - CSS class name for hover elements
+    render_all_styles() - Generate CSS for hover effects
+
+Quick Start:
+    >>> import pysvgchart as psc
+    >>> chart = psc.DonutChart([25, 30, 20, 25], labels=['Q1', 'Q2', 'Q3', 'Q4'])
+    >>> svg = chart.render()
+
+    >>> chart = psc.SimpleLineChart(x_values=[1,2,3], y_values=[[10,20,15]], y_names=['Sales'])
+    >>> chart.add_legend()
+    >>> svg = chart.render()
+
+Documentation:
+    README.rst - Full documentation with examples and API reference
+    CLAUDE.md - Architecture overview for AI assistants and quick reference
+"""
 
 __author__ = "Alex Rowley"
 __email__ = ""

pysvgchart/axes.py

@@ -1,3 +1,22 @@
+"""
+Axis classes for chart rendering.
+
+This module handles axis creation, tick generation, and value-to-pixel positioning.
+
+Classes:
+    Axis: Abstract base class for all axes
+    XAxis: Horizontal axis (values increase left-to-right)
+    YAxis: Vertical axis (values increase bottom-to-top, so pixel Y is inverted)
+    CategoryYAxis: Y-axis for categorical data (preserves order top-to-bottom)
+
+Key responsibilities:
+    - Scale creation via pluggable scale_maker functions
+    - Tick line and label positioning
+    - Grid line storage (populated by chart.add_grids())
+    - Axis title rendering
+
+The get_positions() method converts data values to pixel coordinates using the axis scale.
+"""
 from __future__ import annotations
 from abc import abstractmethod
 from typing import Any, Callable

pysvgchart/charts.py

@@ -1,3 +1,39 @@
+"""
+Chart classes - the main entry points for creating SVG charts.
+
+This module contains all chart types available in pysvgchart:
+- LineChart / SimpleLineChart: Line plots for time series and trends
+- BarChart: Vertical bar charts for category comparisons
+- HorizontalBarChart: Horizontal bars (useful for long category names)
+- NormalisedBarChart: 100% stacked bars for part-of-whole comparisons
+- ScatterChart: Scatter plots for correlation/distribution
+- DonutChart: Pie/donut charts for proportions
+
+Class Hierarchy:
+    Chart (ABC)
+    ├── CartesianChart
+    │   ├── VerticalChart -> LineChart, BarChart, ScatterChart, NormalisedBarChart
+    │   └── HorizontalChart -> HorizontalBarChart
+    └── DonutChart
+
+Typical usage:
+    import pysvgchart as psc
+
+    chart = psc.SimpleLineChart(
+        x_values=[1, 2, 3],
+        y_values=[[10, 20, 15]],
+        y_names=['Sales']
+    )
+    chart.add_legend()
+    svg = chart.render()
+
+Series constructors (internal):
+    - line_series_constructor: Creates LineSeries from data
+    - bar_series_constructor: Creates vertical BarSeries
+    - horizontal_bar_series_constructor: Creates horizontal BarSeries
+    - normalised_bar_series_constructor: Creates 100% stacked bars
+    - scatter_series_constructor: Creates ScatterSeries
+"""
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from itertools import zip_longest, cycle

pysvgchart/helpers.py

@@ -1,3 +1,16 @@
+"""
+Utility functions for chart rendering.
+
+Functions:
+    default_format(value): Format numbers with thousand separators
+    collapse_element_list(*lists): Flatten nested element lists to SVG strings
+    get_numeric_ticks(values, max_ticks, ...): Calculate nice tick values for numeric axes
+    get_logarithmic_ticks(values, max_ticks, ...): Calculate tick values for log scales
+    get_date_or_time_ticks(dates, max_ticks, ...): Calculate ticks for date/datetime ranges
+
+The tick functions implement "nice number" algorithms to find visually appealing
+tick intervals (e.g., 1, 2, 5, 10 rather than 3, 7, 11).
+"""
 import math
 import datetime as dt
 

pysvgchart/legends.py

@@ -1,3 +1,15 @@
+"""
+Legend components for different chart types.
+
+Classes:
+    Legend: Abstract base class
+    LineLegend: For line charts (short line segment + text label)
+    BarLegend: For bar charts (colored rectangle + text label)
+    ScatterLegend: For scatter charts (point shape + text label)
+    DonutLegend: For donut/pie charts (colored circle + text label)
+
+Legends are added via chart.add_legend(x, y) and rendered as part of get_element_list().
+"""
 from abc import abstractmethod
 
 from .helpers import collapse_element_list

pysvgchart/scales.py

@@ -1,3 +1,26 @@
+"""
+Scale classes for mapping data values to chart positions.
+
+Scales determine:
+    - The min/max range of an axis
+    - Tick mark positions (nice round numbers)
+    - How to convert a data value to a 0-1 fraction of the axis
+
+Classes:
+    Scale: Abstract base class
+    MappedLinearScale: Linear scale with optional value mapping (base for Linear/Log)
+    LinearScale: Standard linear scale for numbers, dates, datetimes
+    LogarithmicScale: Logarithmic scale (log10 mapping)
+    MappingScale: Categorical scale for non-numeric values
+
+Factory functions:
+    make_linear_scale(): Creates LinearScale or MappingScale based on value types
+    make_logarithmic_scale(): Creates LogarithmicScale for numeric data
+    make_categories_scale(): Creates MappingScale for categorical data
+
+The value_to_fraction() method is the key interface - converts a data value to
+a proportion (0.0 to 1.0) along the axis, which the Axis then converts to pixels.
+"""
 from __future__ import annotations
 
 from abc import ABC, abstractmethod

pysvgchart/series.py

@@ -1,3 +1,22 @@
+"""
+Data series classes that render chart data as SVG elements.
+
+Each series type converts positioned data points into SVG markup:
+
+Classes:
+    Series: Abstract base class for all data series
+    LineSeries: Renders as SVG path (connected line through points)
+    BarSeries: Renders as vertical rectangles
+    HorizontalBarSeries: Renders as horizontal rectangles
+    ScatterSeries: Renders as point shapes (circles by default)
+    DonutSegment: Renders as arc path for pie/donut charts
+
+Key pattern:
+    - Series store both pixel positions (points) and original data values
+    - pv_generator property yields (point, x_value, y_value) tuples for hover modifiers
+    - get_element_list() returns SVG string fragments
+    - custom_elements list allows adding hover markers and annotations
+"""
 from typing import Callable
 import math
 

pysvgchart/shapes.py

@@ -1,3 +1,28 @@
+"""
+Low-level SVG shape primitives.
+
+These are the building blocks for all chart elements. Each shape knows how to
+render itself as SVG markup via get_element_list().
+
+Classes:
+    Point: 2D coordinate dataclass (x, y)
+    Element: Abstract base class with styles and CSS classes
+    Shape: Abstract positioned element (has position: Point)
+    Line: SVG <line> element
+    Circle: SVG <circle> element
+    Rect: SVG <rect> element
+    Text: SVG <text> element
+    Group: SVG <g> container for multiple elements
+
+Common patterns:
+    - All shapes have styles (dict of SVG attributes) and classes (CSS class names)
+    - attributes property formats styles/classes for SVG attribute string
+    - Shapes can be added to charts via chart.add_custom_element(shape)
+
+Example:
+    text = Text(x=100, y=50, content='Label', styles={'fill': 'red'})
+    circle = Circle(x=200, y=100, radius=5, classes=['highlight'])
+"""
 from abc import ABC, abstractmethod
 from dataclasses import dataclass