# HTML Reports

The Truthound Data Docs module transforms data profile results into self-contained HTML reports.

## Quick Start

```python
from truthound.datadocs import generate_html_report, HTMLReportBuilder

# Simple usage
html = generate_html_report(
    profile=profile_dict,
    title="Data Quality Report",
    theme="professional",
    output_path="report.html",
)

# Generate from file
from truthound.datadocs import generate_report_from_file

html = generate_report_from_file(
    profile_path="profile.json",
    output_path="report.html",
    title="My Report",
    theme="dark",
)
```

## HTMLReportBuilder

Use `HTMLReportBuilder` directly when fine-grained control is required.

### Basic Usage

```python
from truthound.datadocs import HTMLReportBuilder, ReportTheme

builder = HTMLReportBuilder(theme=ReportTheme.PROFESSIONAL)
html = builder.build(
    profile=profile_dict,
    title="My Data Report",
    subtitle="Q4 2025 Analysis",
    description="Customer dataset quality analysis",
)
builder.save(html, "report.html")
```

### Detailed Configuration with ReportConfig

```python
from truthound.datadocs import (
    HTMLReportBuilder,
    ReportConfig,
    ReportTheme,
    SectionType,
)

config = ReportConfig(
    # Theme
    theme=ReportTheme.DARK,

    # Sections to include (in order)
    sections=[
        SectionType.OVERVIEW,
        SectionType.QUALITY,
        SectionType.COLUMNS,
        SectionType.PATTERNS,
        SectionType.DISTRIBUTION,
        SectionType.CORRELATIONS,
        SectionType.RECOMMENDATIONS,
        SectionType.ALERTS,
    ],

    # Layout options
    include_toc=True,
    include_header=True,
    include_footer=True,
    include_timestamp=True,
    include_download_button=True,
    embed_resources=True,
    minify_html=False,

    # Custom content
    custom_css="",
    custom_js="",
    logo_url=None,
    logo_base64=None,
    footer_text="Generated by Truthound",

    # Localization
    language="en",
    date_format="%Y-%m-%d %H:%M:%S",
    number_format=",.2f",
)

builder = HTMLReportBuilder(config=config)
html = builder.build(profile_dict)
```

## ProfileDataConverter

`ProfileDataConverter` transforms TableProfile data into report-ready structures.

```python
from truthound.datadocs.builder import ProfileDataConverter

converter = ProfileDataConverter(profile_dict)

# Extract overview metrics
metrics = converter.get_overview_metrics()
# {
#     "row_count": 10000,
#     "column_count": 15,
#     "memory_bytes": 1234567,
#     "duplicate_rows": 123,
#     "null_cells": 456,
#     "quality_score": 85.5,
# }

# Column data
columns = converter.get_column_data()

# Generate chart specs
type_chart = converter.get_type_distribution()  # ChartSpec
null_chart = converter.get_null_distribution()  # ChartSpec
unique_chart = converter.get_uniqueness_distribution()  # ChartSpec

# Extract patterns
patterns = converter.get_patterns()

# Extract correlations
correlations = converter.get_correlations()  # list[tuple[str, str, float]]

# Generate alerts
alerts = converter.get_alerts()  # list[AlertSpec]

# Generate recommendations
recommendations = converter.get_recommendations()  # list[str]
```

## Convenience Functions

### generate_html_report

```python
from truthound.datadocs import generate_html_report

html = generate_html_report(
    profile=profile_dict,        # TableProfile dict or object
    title="Data Quality Report", # Report title
    subtitle="",                 # Subtitle
    theme="professional",        # Theme name or ReportTheme
    output_path="report.html",   # Save path (optional)
)
```

### generate_report_from_file

```python
from truthound.datadocs import generate_report_from_file

html = generate_report_from_file(
    profile_path="profile.json",  # Profile JSON file path
    output_path="report.html",    # Output path (default: <input>.html)
    title="My Report",
    theme="dark",
)
```

### export_report

```python
from truthound.datadocs import export_report

# HTML export
export_report(profile_dict, "report.html", format="html")

# PDF export (requires WeasyPrint)
export_report(profile_dict, "report.pdf", format="pdf")
```

## Complete Workflow Example

```python
import truthound as th
from truthound.datadocs import generate_html_report

# 1. Load data
df = th.load("data.csv")

# 2. Generate profile
from truthound.profiler import DataProfiler
profiler = DataProfiler()
profile = profiler.profile(df)

# 3. Generate HTML report
html = generate_html_report(
    profile=profile.to_dict(),
    title="Customer Data Quality Report",
    subtitle="Q4 2025 Analysis",
    theme="professional",
    output_path="customer_report.html",
)

print(f"Report generated: {len(html):,} bytes")
```

## CLI Usage

```bash
# Basic usage
truthound docs generate profile.json -o report.html

# Custom title and dark theme
truthound docs generate profile.json -o report.html \
    --title "Q4 Data Quality Report" \
    --subtitle "Customer Dataset" \
    --theme dark

# PDF export
truthound docs generate profile.json -o report.pdf --format pdf
```

## Customization

### Custom CSS

```python
config = ReportConfig(
    custom_css="""
    .report-title {
        color: #ff6b6b;
    }
    .metric-card {
        border: 2px solid #4ecdc4;
    }
    """,
)
```

### Custom JavaScript

```python
config = ReportConfig(
    custom_js="""
    document.addEventListener('DOMContentLoaded', function() {
        console.log('Report loaded!');
    });
    """,
)
```

### Adding a Logo

```python
# Add logo via URL
config = ReportConfig(logo_url="https://example.com/logo.png")

# Add logo via Base64 (offline support)
import base64
with open("logo.png", "rb") as f:
    logo_b64 = base64.b64encode(f.read()).decode()

config = ReportConfig(logo_base64=f"data:image/png;base64,{logo_b64}")
```

## API Reference

### ReportConfig

```python
@dataclass
class ReportConfig:
    theme: ReportTheme = ReportTheme.PROFESSIONAL
    custom_theme: ThemeConfig | None = None
    chart_library: ChartLibrary = ChartLibrary.APEXCHARTS
    sections: list[SectionType] = [
        SectionType.OVERVIEW,
        SectionType.QUALITY,
        SectionType.COLUMNS,
        SectionType.PATTERNS,
        SectionType.DISTRIBUTION,
        SectionType.CORRELATIONS,
        SectionType.RECOMMENDATIONS,
        SectionType.ALERTS,
    ]
    include_toc: bool = True
    include_header: bool = True
    include_footer: bool = True
    include_timestamp: bool = True
    include_download_button: bool = True
    embed_resources: bool = True
    minify_html: bool = False
    custom_css: str = ""
    custom_js: str = ""
    logo_url: str | None = None
    logo_base64: str | None = None
    footer_text: str = "Generated by Truthound"
    language: str = "en"
    date_format: str = "%Y-%m-%d %H:%M:%S"
    number_format: str = ",.2f"
```

### ReportMetadata

```python
@dataclass
class ReportMetadata:
    title: str
    subtitle: str = ""
    description: str = ""
    data_source: str = ""
    created_at: datetime = field(default_factory=datetime.now)
    author: str = ""
    version: str = ""
```

## See Also

- [Themes](themes.md) - Theme customization
- [Charts](charts.md) - Chart rendering
- [Sections](sections.md) - Section configuration
- [PDF Export](pdf-export.md) - PDF export
