docs: add MkDocs Material site + GitHub Pages deploy

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: docs
+
+# Build the MkDocs Material site and deploy it to GitHub Pages.
+# Requires: Settings -> Pages -> Source: "GitHub Actions" (one-time, manual).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment; don't cancel an in-progress one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - run: pip install -r docs/requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - 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

@@ -21,3 +21,5 @@ test.py
 .venv/
 # generated by setuptools-scm at build time
 PyReconstruct/_version.py
+# MkDocs build output
+site/

docs/USER_GUIDE.md

@@ -16,7 +16,7 @@ The University of Texas at Austin) and the in-app **Help ▸ Shortcuts list**.
 >
 > > 📸 *Screenshot: short description of what to capture.*
 >
-> Contributions of screenshots are welcome — see [CONTRIBUTING.md](../CONTRIBUTING.md).
+> Contributions of screenshots are welcome — see [CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md).
 
 > **Shortcuts.** Key combinations shown here are the **defaults**. Almost all of
 > them are rebindable under **Help ▸ Shortcuts list** (press `?`). A few menu
@@ -99,7 +99,7 @@ PyReconstruct
 `pip` pulls in the runtime dependencies (PySide6, VTK, vedo, NumPy, SciPy,
 scikit-image, shapely, trimesh, zarr, and others). For a full development setup
 (conda environment, tests, code layout), see
-[CONTRIBUTING.md](../CONTRIBUTING.md).
+[CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md).
 
 ### Launching the app
 
@@ -923,5 +923,5 @@ the original **Reconstruct** by John C. Fiala.
 
 This distribution is independently developed and maintained by **Dusten Hubbard**
 (Kristen Harris Lab, **The University of Texas at Austin**). See the
-[README](../README.md) for provenance, performance notes, and citation details, and
-[CONTRIBUTING.md](../CONTRIBUTING.md) to help improve PyReconstruct.
+[README](https://github.com/dustenhubbard/PyReconstruct/blob/main/README.md) for provenance, performance notes, and citation details, and
+[CONTRIBUTING.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md) to help improve PyReconstruct.

docs/index.md

@@ -0,0 +1,48 @@
+# PyReconstruct
+
+PyReconstruct is an open-source desktop application for tracing, annotating, and
+3D-reconstructing serial-section and volume electron-microscopy (EM) data. It is
+the modern, actively maintained successor to *Reconstruct*.
+
+This site documents an independently developed and maintained distribution of
+PyReconstruct. It tracks the upstream
+[SynapseWeb/PyReconstruct](https://github.com/SynapseWeb/PyReconstruct) project
+and builds on it with 3-4x faster open and refresh on large series, one-click
+installers, an in-app updater, and ongoing user-interface modernization.
+
+## Who it's for
+
+Neuroscientists and EM researchers who trace neural structures across stacks of
+serial sections - segmenting objects, aligning sections, measuring morphology,
+and building 3D reconstructions of cells, organelles, and synapses from
+volume-EM datasets. It reads and writes the `.jser` series format and handles
+large autosegmented series with hundreds of thousands of traces.
+
+## Install
+
+Download a one-click build (Windows `.exe`, macOS `.dmg`, or Linux installer)
+from
+**[Releases](https://github.com/dustenhubbard/PyReconstruct/releases)** - no
+Python required. Developers can install from source with `pip` or `uv`.
+
+Full instructions, including the macOS Gatekeeper step and the in-app updater,
+are in the [User Guide](USER_GUIDE.md#1-installing-pyreconstruct).
+
+## Where to go next
+
+- **[User Guide](USER_GUIDE.md)** - install, open a series, the tracing tools,
+  data lists, alignment, 3D reconstruction, and backups.
+- **[Performance](performance.md)** - benchmarks for the fork's speed work.
+- **[Developing with uv](DEV_UV.md)** - the uv-based development workflow.
+- **[Contributing](https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md)**
+  - dev setup, branch/commit conventions, tests, and the PR process.
+- **[Source code](https://github.com/dustenhubbard/PyReconstruct)** and
+  **[issues](https://github.com/dustenhubbard/PyReconstruct/issues)** on GitHub.
+
+## Citation
+
+PyReconstruct was developed in the Kristen Harris Lab at **The University of
+Texas at Austin** and introduced in *PNAS* (2025),
+[doi:10.1073/pnas.2505822122](https://doi.org/10.1073/pnas.2505822122). See the
+[README](https://github.com/dustenhubbard/PyReconstruct/blob/main/README.md)
+for full provenance, performance notes, and citation details.

docs/performance.md

@@ -0,0 +1,42 @@
+# Performance
+
+This distribution is significantly faster than the upstream it forked from on the
+open and refresh paths that dominate day-to-day work on large series - **up to
+4.19x faster** to open and refresh a series, with **exact geometry equivalence**
+(the speedup is not from skipped work).
+
+The wins are algorithmic and single-threaded (NumPy-vectorized trace geometry,
+deferred Feret-diameter computation, NumPy point mapping, orjson-backed `.jser`
+I/O, and scoped object operations), so they help every machine and
+disproportionately help the large autosegmented series that were previously near
+unusable.
+
+## Headline results
+
+Median of repeated runs, upstream origin to this fork:
+
+| Series | Size | Traces | Open (origin -> fork) | Open+Refresh speedup |
+|---|--:|--:|---|--:|
+| crop_1 | 6 MB | 2209 | 1.115 -> 0.325s | 3.44x |
+| ZGBJY | 7 MB | 2511 | 1.733 -> 0.409s | 4.19x |
+| crop_2 | 92 MB | 27525 | 18.87 -> 4.78s | 3.84x |
+| GBSFW | 127 MB | 61121 | 28.32 -> 8.76s | 3.18x |
+| NVWXP | 187 MB | 83126 | 38.79 -> 12.04s | 3.2x |
+| crop_3 | 312 MB | 89388 | 63.24 -> 16.95s | 3.69x |
+| crop_4 | 701 MB | 204622 | 143.14 -> 48.52s | 3.29x |
+| crop_ROIsmall | 1400 MB | 492574 | 288.27 -> 100.10s | 3.11x |
+
+Per-series geometry equivalence (section, object, and trace counts, plus summed
+area / length / radius) is exact across the board.
+
+## Full report and method
+
+The complete report - including the equivalence checks, per-commit attribution,
+hardware and dependency versions, and the measurement methodology - and the
+reproducible benchmark harness live in the repository:
+
+- **[benchmarks/REPORT.md](https://github.com/dustenhubbard/PyReconstruct/blob/main/benchmarks/REPORT.md)**
+  - the full report.
+- **[benchmarks/](https://github.com/dustenhubbard/PyReconstruct/tree/main/benchmarks)**
+  - the harness (`harness.py`, `orchestrate.py`, `build_report.py`) and raw
+  results.

docs/requirements.txt

@@ -0,0 +1,3 @@
+# Documentation build dependencies (MkDocs Material docs site).
+# mkdocs-material pulls in mkdocs, pymdown-extensions, and the search plugin.
+mkdocs-material==9.7.6

mkdocs.yml

@@ -0,0 +1,52 @@
+site_name: PyReconstruct
+site_description: >-
+  Tracing, annotation, and 3D reconstruction for serial-section and volume
+  electron microscopy.
+site_url: https://dustenhubbard.github.io/PyReconstruct/
+repo_url: https://github.com/dustenhubbard/PyReconstruct
+repo_name: dustenhubbard/PyReconstruct
+edit_uri: edit/main/docs/
+docs_dir: docs
+
+theme:
+  name: material
+  icon:
+    repo: fontawesome/brands/github
+  features:
+    - navigation.instant
+    - navigation.top
+    - navigation.sections
+    - search.suggest
+    - content.code.copy
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: teal
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: teal
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+plugins:
+  - search
+
+markdown_extensions:
+  - toc:
+      permalink: true
+  - pymdownx.highlight
+  - pymdownx.superfences
+
+nav:
+  - Home: index.md
+  - User Guide: USER_GUIDE.md
+  - Performance: performance.md
+  - Developing with uv: DEV_UV.md
+  - Contributing: https://github.com/dustenhubbard/PyReconstruct/blob/main/CONTRIBUTING.md
+  - Security: https://github.com/dustenhubbard/PyReconstruct/blob/main/SECURITY.md