docs: restructure into guides/reference and add a MkDocs Material site

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+# Build the MkDocs site and publish it to GitHub Pages.
+#
+# One-time setup: in the repository settings, set Pages -> "Build and deployment"
+# -> Source to "GitHub Actions". The site is then served at
+# https://nely-epfl.github.io/deeperfly/ and rebuilt on every push to main.
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress run.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build site
+        run: uv run --group docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -31,3 +31,6 @@ deeperfly_outputs*/
 
 # Scratch / working files (not for version control)
 scratch/
+
+# MkDocs build output
+site/

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to deeperfly
 
 Development setup. For how the pipeline works, see
-[docs/architecture.md](docs/architecture.md).
+[docs/explanation/pipeline.md](docs/explanation/pipeline.md).
 
 ## Requirements
 
@@ -47,6 +47,22 @@ The hooks run ruff, keep `uv.lock` in sync, and strip notebook outputs with
 uvx pre-commit run --all-files
 ```
 
+## Documentation
+
+The docs site is built with [MkDocs](https://www.mkdocs.org/) + Material and
+lives in [`docs/`](docs) (configured by [`mkdocs.yml`](mkdocs.yml)). The library
+API reference is generated from the source docstrings by
+[mkdocstrings](https://mkdocstrings.github.io/). Preview it locally with live
+reload:
+
+```bash
+uv run --group docs mkdocs serve       # http://127.0.0.1:8000
+uv run --group docs mkdocs build --strict   # what CI runs
+```
+
+Pushing to `main` rebuilds and publishes the site to GitHub Pages
+(see [`.github/workflows/docs.yml`](.github/workflows/docs.yml)).
+
 ## License
 
 By contributing you agree that your contributions are licensed under the

README.md

@@ -2,74 +2,55 @@
 
 Markerless 3D pose estimation of tethered *Drosophila* from a multi-camera rig.
 It estimates camera parameters and 2D/3D keypoint locations from behavioral
-recordings: 2D pose → bundle adjustment → triangulation → visualization.
+recordings through one linear pipeline: 2D pose → bundle adjustment →
+triangulation → visualization.
 
-It is a modern rewrite of
-[DeepFly3D](https://github.com/NeLy-EPFL/DeepFly3D),
+deeperfly is both a command-line tool and a Python library, and a modern rewrite
+of [DeepFly3D](https://github.com/NeLy-EPFL/DeepFly3D),
 [DeepFly2D](https://github.com/NeLy-EPFL/DeepFly2D) and
-[PyBundleAdjustment](https://github.com/semihgunel/PyBundleAdjustment). See [docs/comparison.md](docs/comparison.md) for how it differs
-from the originals.
+[PyBundleAdjustment](https://github.com/semihgunel/PyBundleAdjustment).
+
+📖 **[Documentation](https://nely-epfl.github.io/deeperfly/)**
 
 ## Installation
 
-deeperfly is both a command-line tool and a Python library. Install the CLI with
-[uv](https://docs.astral.sh/uv/):
+Install the CLI with [uv](https://docs.astral.sh/uv/) (`--torch-backend=auto`
+picks the right PyTorch wheel for your machine):
 
 ```bash
 uv tool install git+https://github.com/NeLy-EPFL/deeperfly --python 3.13 --torch-backend=auto
 ```
 
-## Checking your install
-
-`deeperfly doctor` reports what this machine can run — inference, frame I/O
-backends, detector weights, and the default config path. Run it after installing:
+As a library in your own project (prefix with `UV_TORCH_BACKEND=auto`, since
+`uv add` has no `--torch-backend` flag):
 
 ```bash
-deeperfly doctor
-```
-
-The `GPU inference` line under `inference` tells you whether the detector will
-run on the GPU:
-
-```
-  GPU inference     available (24.0 GiB memory)
+UV_TORCH_BACKEND=auto uv add git+https://github.com/NeLy-EPFL/deeperfly
 ```
 
-On a CPU-only box it reads `not available -- CPU only`.
-
-## Quickstart
+## Usage
 
 ```bash
-deeperfly init config.toml                               # write a config you can edit
-deeperfly run recording/ -c config.toml                  # run the full pipeline
-deeperfly inspect recording/deeperfly_outputs/poses.h5   # inspect the result
+deeperfly doctor                                         # what this machine can run
+deeperfly run recording/                                 # detect 2D -> 3D -> video
+deeperfly inspect recording/deeperfly_outputs/poses.h5   # summarize the result
 ```
 
 `deeperfly run` does everything in one command: detect 2D pose in every view,
-bundle-adjust the cameras, triangulate to 3D, then render a skeleton video. Outputs
-land in `recording/deeperfly_outputs/` (override with
-`-o`): `poses.h5`, the rendered video, and a copy of the config used.
+bundle-adjust the cameras, triangulate to 3D, then render skeleton videos.
+Outputs land in `recording/deeperfly_outputs/` (override with `-o`): `poses.h5`,
+the rendered videos, and a snapshot of the config used. `deeperfly doctor`
+reports whether the detector will run on the GPU and where the weights are
+cached.
 
-The config is optional — `deeperfly run recording/` uses sensible defaults.
-Generate one with `deeperfly init` to point at your cameras or tweak the
-pipeline; the generated file is commented, so edit it in place. See
-[docs/configuration.md](docs/configuration.md) for what each section does — from
-the `[inputs]` file-to-camera mapping you'll almost always set, through resuming
-and partial runs, to the rig and skeleton you can usually leave at their
-defaults.
+## Configuration
 
-Pass `--log-level debug` for more detail, or `--log-level warning` to quiet the
-per-stage logs and progress bar.
-
-## Library usage
-
-deeperfly is also a Python library. Add it to your project — prefix with
-`UV_TORCH_BACKEND=auto` so uv picks the right PyTorch wheel (`uv add` has no
-`--torch-backend` flag):
-
-```bash
-UV_TORCH_BACKEND=auto uv add git+https://github.com/NeLy-EPFL/deeperfly
-```
+A run is driven by a single, self-contained `config.toml` — the camera rig, which
+file belongs to which camera, the detector, the pipeline and the visualization.
+It's optional (`deeperfly run recording/` uses sensible defaults); generate a
+commented one to edit with `deeperfly init config.toml` and pass it with `-c`.
+Each stage is toggled by a `do_<stage>` switch and reuses its cached result when
+unchanged, so editing the config recomputes only the affected stages.
 
 ```python
 from deeperfly import CameraGroup, Config, Skeleton, run_from_points2d
@@ -79,16 +60,14 @@ result = run_from_points2d(cameras, Skeleton.fly(), pts2d, conf)
 result.save("fly.h5")
 ```
 
-See [docs/library.md](docs/library.md) and the [`examples/`](examples) notebooks
-for full walkthroughs.
-
 ## Documentation
 
-- [docs/configuration.md](docs/configuration.md) — the `config.toml`, section by section, ordered by how often you'll edit it.
-- [docs/library.md](docs/library.md) — the Python API: bundle adjustment, the pipeline, video I/O.
-- [docs/architecture.md](docs/architecture.md) — how the pipeline works: stages, 3D correction (triangulation ransac/greedy/dlt ± pictorial), the detector.
-- [docs/video.md](docs/video.md) — frame read/write: PyAV video, OpenCV image sequences (CPU decode).
-- [docs/comparison.md](docs/comparison.md) — what changed from DeepFly3D / DeepFly2D / PyBundleAdjustment.
+Full docs are at **[nely-epfl.github.io/deeperfly](https://nely-epfl.github.io/deeperfly/)**:
+
+- [Getting started](https://nely-epfl.github.io/deeperfly/getting-started/) — run the bundled example end to end.
+- [CLI usage](https://nely-epfl.github.io/deeperfly/guides/cli/) and [Writing configs](https://nely-epfl.github.io/deeperfly/guides/configuration/).
+- [How it works](https://nely-epfl.github.io/deeperfly/explanation/pipeline/) — the pipeline, stage by stage.
+- [Library API](https://nely-epfl.github.io/deeperfly/guides/library/) and the complete [reference](https://nely-epfl.github.io/deeperfly/reference/api/).
 - [CONTRIBUTING.md](CONTRIBUTING.md) — development install, tests, linting.
 
 ## License