feat: mkdocs/readthedocs

.github/workflows/docs.yml

@@ -0,0 +1,21 @@
+name: Read the Docs PR preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".readthedocs.yaml"
+
+permissions:
+  pull-requests: write
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "fgmetric"

.readthedocs.yaml

@@ -0,0 +1,21 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs
+    build:
+      html:
+        - uv run --frozen mkdocs build --strict --site-dir "${READTHEDOCS_OUTPUT}/html"
+
+mkdocs:
+  configuration: mkdocs.yml

README.md

@@ -2,6 +2,7 @@
 
 Type-validated Python models for delimited data files.
 
+[![Docs](https://readthedocs.org/projects/fgmetric/badge/?version=stable)](https://fgmetric.readthedocs.io/)
 [![CI](https://github.com/fulcrumgenomics/fgmetric/actions/workflows/python_package.yml/badge.svg?branch=main)](https://github.com/fulcrumgenomics/fgmetric/actions/workflows/python_package.yml?query=branch%3Amain)
 [![Python Versions](https://img.shields.io/badge/python-3.12_|_3.13-blue)](https://github.com/fulcrumgenomics/fgmetric)
 [![MyPy Checked](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)

docs/api/metric.md

@@ -0,0 +1,7 @@
+# Metric
+
+::: fgmetric.Metric
+    options:
+      show_bases: false
+      members:
+        - read

docs/api/metric_writer.md

@@ -0,0 +1,10 @@
+# MetricWriter
+
+::: fgmetric.MetricWriter
+    options:
+      show_bases: false
+      members:
+        - __init__
+        - write
+        - writeall
+        - close

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/guide.md

@@ -0,0 +1,148 @@
+# User Guide
+
+## Defining a Metric
+
+A `Metric` is a Pydantic model that maps to rows in a delimited file.
+Define one by subclassing `Metric` and declaring fields with type annotations:
+
+```python
+from fgmetric import Metric
+
+
+class AlignmentMetric(Metric):
+    read_name: str
+    mapping_quality: int
+    is_duplicate: bool = False
+```
+
+Each field corresponds to a column in your file.
+Pydantic handles type coercion automatically --- string values like `"60"` become `int`, `"true"` becomes `bool`, and so on.
+
+## Reading Metrics
+
+Use the `read()` class method to iterate over rows in a delimited file:
+
+```python
+from pathlib import Path
+
+for metric in AlignmentMetric.read(Path("alignments.tsv")):
+    print(f"{metric.read_name}: MQ={metric.mapping_quality}")
+```
+
+`read()` yields one `Metric` instance per row, lazily --- so you can process files larger than memory.
+If any row fails validation, Pydantic raises a `ValidationError` with details about which field failed and why.
+
+Example input file (`alignments.tsv`):
+
+```tsv
+read_name	mapping_quality	is_duplicate
+read1	60	false
+read2	30	true
+```
+
+### Custom Delimiters
+
+By default, `read()` expects tab-separated values. Pass a `delimiter` argument for other formats:
+
+```python
+# Reading CSV files
+for metric in AlignmentMetric.read(Path("data.csv"), delimiter=","):
+    ...
+```
+
+### Empty Fields
+
+Empty fields in optional columns are automatically converted to `None`:
+
+```python
+class QualityMetric(Metric):
+    sample: str
+    score: float | None  # Empty string in file becomes None
+```
+
+## Writing Metrics
+
+Use `MetricWriter` as a context manager to write metrics to a file:
+
+```python
+from fgmetric import MetricWriter
+
+metrics = [
+    AlignmentMetric(read_name="read1", mapping_quality=60),
+    AlignmentMetric(read_name="read2", mapping_quality=30, is_duplicate=True),
+]
+
+with MetricWriter(AlignmentMetric, Path("output.tsv")) as writer:
+    writer.writeall(metrics)
+```
+
+The writer automatically outputs the header row based on the Metric's field names.
+You can also write one metric at a time with `writer.write(metric)`.
+
+### Custom Delimiters
+
+Just like reading, writing supports custom delimiters:
+
+```python
+with MetricWriter(AlignmentMetric, Path("output.csv"), delimiter=",") as writer:
+    writer.writeall(metrics)
+```
+
+## List Fields
+
+Fields typed as `list[T]` are automatically parsed from and serialized to delimited strings:
+
+```python
+class TaggedRead(Metric):
+    read_id: str
+    tags: list[str]           # "A,B,C" becomes ["A", "B", "C"]
+    scores: list[int]         # "1,2,3" becomes [1, 2, 3]
+    optional_tags: list[str] | None  # "" becomes None
+```
+
+The list delimiter defaults to `,` but can be customized per-metric with the `collection_delimiter` class variable:
+
+```python
+class SemicolonMetric(Metric):
+    collection_delimiter = ";"
+    values: list[int]  # "1;2;3" becomes [1, 2, 3]
+```
+
+## Counter Fields
+
+When your file has categorical data with one column per category (e.g. base counts A, C, G, T), you can model them as a single `Counter[StrEnum]` field:
+
+```python
+from collections import Counter
+from enum import StrEnum
+
+from fgmetric import Metric
+
+
+class Base(StrEnum):
+    A = "A"
+    C = "C"
+    G = "G"
+    T = "T"
+
+
+class BaseCountMetric(Metric):
+    position: int
+    counts: Counter[Base]
+```
+
+Given an input file:
+
+```tsv
+position	A	C	G	T
+1	10	5	3	2
+```
+
+This parses to:
+
+```python
+BaseCountMetric(position=1, counts=Counter({Base.A: 10, Base.C: 5, Base.G: 3, Base.T: 2}))
+```
+
+The enum members define both the expected column names and the keys in the resulting `Counter`.
+When writing, the `Counter` is "pivoted" back into separate columns.

docs/index.md

@@ -0,0 +1,60 @@
+# fgmetric
+
+[![CI](https://github.com/fulcrumgenomics/fgmetric/actions/workflows/python_package.yml/badge.svg?branch=main)](https://github.com/fulcrumgenomics/fgmetric/actions/workflows/python_package.yml?query=branch%3Amain)
+[![Python Versions](https://img.shields.io/badge/python-3.12_|_3.13-blue)](https://github.com/fulcrumgenomics/fgmetric)
+[![MyPy Checked](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+
+**Type-validated Python models for delimited data files.**
+
+`fgmetric` lets you define Python classes ("Metrics") that map directly to rows in CSV/TSV files.
+It handles parsing, type coercion (strings to int, float, bool), and validation automatically using [Pydantic](https://docs.pydantic.dev/latest/).
+
+## Installation
+
+=== "pip"
+
+    ```console
+    pip install fgmetric
+    ```
+
+=== "uv"
+
+    ```console
+    uv add fgmetric
+    ```
+
+## Quick Example
+
+Define a class to represent each row, then read or write:
+
+```python
+from pathlib import Path
+from fgmetric import Metric, MetricWriter
+
+
+class AlignmentMetric(Metric):
+    read_name: str
+    mapping_quality: int
+    is_duplicate: bool = False
+
+
+# Reading
+for metric in AlignmentMetric.read(Path("alignments.tsv")):
+    print(f"{metric.read_name}: MQ={metric.mapping_quality}")
+
+# Writing
+metrics = [
+    AlignmentMetric(read_name="read1", mapping_quality=60),
+    AlignmentMetric(read_name="read2", mapping_quality=30, is_duplicate=True),
+]
+with MetricWriter(AlignmentMetric, Path("output.tsv")) as writer:
+    writer.writeall(metrics)
+```
+
+## Why fgmetric?
+
+- **vs. csv + dataclasses** --- Automatic type coercion and validation without boilerplate. Built on Pydantic, so custom validators and serializers can be readily added.
+- **vs. pandas** --- Processes records lazily, handling files larger than memory. Metrics are type-validated and can be made immutable.
+- **vs. Pydantic alone** --- Handles CSV/TSV specifics (header parsing, delimiter configuration) and provides out-of-the-box features like empty value handling and Counter field pivoting.
+
+[Get started with the User Guide](guide.md)

mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: fgmetric
+site_url: https://fgmetric.readthedocs.io/en/stable/
+site_description: Type-validated Python models for delimited data files.
+repo_name: fulcrumgenomics/fgmetric
+repo_url: https://github.com/fulcrumgenomics/fgmetric
+
+nav:
+  - Home: index.md
+  - User Guide: guide.md
+  - API Reference:
+      - Metric: api/metric.md
+      - MetricWriter: api/metric_writer.md
+  - Benchmarks: benchmarks.md
+  - Contributing: contributing.md
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - content.code.copy
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.sections
+    - navigation.top
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.snippets:
+      base_path: ["."]
+  - toc:
+      permalink: true
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            merge_init_into_class: true
+            members_order: source
+            separate_signature: true
+            show_root_heading: true
+            show_source: false
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true

pyproject.toml

@@ -31,6 +31,7 @@ classifiers     = [
 "homepage" = "https://github.com/fulcrumgenomics/fgmetric"
 "repository" = "https://github.com/fulcrumgenomics/fgmetric"
 "Bug Tracker" = "https://github.com/fulcrumgenomics/fgmetric/issues"
+"documentation" = "https://fgmetric.readthedocs.io/"
 
 [dependency-groups]
 dev = [
@@ -45,6 +46,11 @@ dev = [
 ipython = [
     "ipython ~=9.2",
 ]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material ~=9.6",
+    "mkdocstrings[python] ~=0.29",
+]
 
 [project.optional-dependencies]
 benchmark = [
@@ -85,6 +91,9 @@ fix-and-check-all.sequence    = [
     "check-tests"
 ]
 
+docs-build = "mkdocs build --strict"
+docs-serve = "mkdocs serve"
+
 benchmark = "pytest --no-cov --benchmark-group-by param:num_rows --override-ini testpaths=tests/benchmarks"
 
 [tool.mypy]