Add static documentation site

.github/workflows/website.yml

@@ -0,0 +1,65 @@
+name: Website
+
+on:
+  pull_request:
+    paths:
+      - "index.md"
+      - "README.md"
+      - "MODEL_CARD.md"
+      - "docs/**"
+      - "assets/dohnuts-logo.png"
+      - "results/**"
+      - "pyproject.toml"
+      - "LICENSE"
+      - "NOTICE"
+      - ".github/workflows/website.yml"
+  push:
+    branches: [main]
+    paths:
+      - "index.md"
+      - "README.md"
+      - "MODEL_CARD.md"
+      - "docs/**"
+      - "assets/dohnuts-logo.png"
+      - "results/**"
+      - "pyproject.toml"
+      - "LICENSE"
+      - "NOTICE"
+      - ".github/workflows/website.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: docs/requirements.txt
+      - run: python -m pip install -r docs/requirements.txt
+      - run: python -m sphinx -b html -W --keep-going -d build/doctrees -c docs . build/site
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: build/site
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

MODEL_CARD.md

@@ -6,8 +6,6 @@ ordered scores. Independent questions about one input share computation in a
 single forward pass. The interface returns decisions without generating reasoning
 or free-form answers.
 
-![Dohnuts 0.1.0 model overview and benchmarks](docs/figures/overview.svg)
-
 ## Model details
 
 | Property | Value |
@@ -44,6 +42,8 @@ for agent use.
 
 ## Evaluation
 
+![Dohnuts 0.1.0 model overview and benchmarks](docs/figures/overview.svg)
+
 The model achieves **78.21% macro accuracy** over 26 held-out dataset groups
 containing 180,031 decisions. Each group contributes equally to this mean.
 Development data selects weights; calibration data fits temperatures; test data
@@ -121,7 +121,7 @@ merged before temperature fitting and final evaluation. The
 ### Training datasets
 
 The 26 training groups are derived from the following source datasets. Hub links
-identify the datasets; the [download manifests](data/manifests/) pin the files,
+identify the datasets; the [download manifests](https://github.com/PsiACE/dohnuts/tree/main/data/manifests) pin the files,
 revisions, and checksums actually used, including official archives downloaded
 outside the Hub.
 
@@ -182,3 +182,10 @@ own research-use terms.
 The checkpoint is not offered as a commercially cleared model. See the
 [data reference](docs/data-and-evaluation.md#release-assets-and-terms) and
 [attributions](NOTICE).
+
+```{toctree}
+:hidden:
+
+Benchmark comparisons <docs/figures/README>
+Evaluation results <results/README>
+```

README.md

@@ -14,8 +14,6 @@ The 0.8B model runs locally on a consumer GPU.
 
 [Model](https://huggingface.co/PsiACE/Dohnuts-0.1.0-0.8B) · [Model card](MODEL_CARD.md) · [Documentation](docs/README.md) · [Benchmarks](docs/figures/README.md)
 
-![Dohnuts 0.1.0 model overview and benchmarks](docs/figures/overview.svg)
-
 ## One message, several decisions
 
 Route a support request and check whether it asks for a refund in the same call:
@@ -63,6 +61,8 @@ comparisons against Jev, Laya multilingual, and Laya Vision. For agents,
 [Bub integration](docs/bub-agent.md) exposes the same interface as one decision
 tool through the Bub SDK.
 
+![Dohnuts 0.1.0 model overview and benchmarks](docs/figures/overview.svg)
+
 ## Built at home
 
 We developed, trained, calibrated, and evaluated Dohnuts on a home PC with one

docs/README.md

@@ -22,3 +22,14 @@
 
 The [behavior and regression tests](design.md#behavior-and-regression-tests)
 cover the prediction interface and known failure cases.
+
+For website contributors, see [Build the website](website.md).
+
+```{toctree}
+:hidden:
+
+Installation and inference <inference>
+Agent integration <bub-agent>
+Training and evaluation <run-experiment>
+Build the website <website>
+```

docs/_static/brand.css

@@ -0,0 +1,97 @@
+/* Keep Furo's layout and controls; add only the Dohnuts brand treatment. */
+body {
+  --font-stack: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-stack--monospace: ui-monospace, "SFMono-Regular", Consolas, monospace;
+  --code-font-size: 0.875rem;
+  --toc-font-size: 0.875rem;
+  --toc-title-font-size: 0.875rem;
+}
+
+.sidebar-brand {
+  flex-direction: row;
+  align-items: center;
+  gap: 0.65rem;
+}
+
+.sidebar-logo {
+  width: 3.5rem;
+  margin: 0;
+}
+
+.sidebar-brand-text {
+  font-size: 1.5rem;
+  font-weight: 750;
+}
+
+h1,
+h2,
+h3 {
+  font-weight: 700;
+}
+
+h1 {
+  letter-spacing: -0.035em;
+  overflow-wrap: anywhere;
+}
+
+a {
+  text-underline-offset: 0.18em;
+}
+
+a:focus-visible,
+button:focus-visible,
+input:focus-visible,
+label:focus-visible {
+  outline: 2px solid var(--color-brand-primary);
+  outline-offset: 3px;
+}
+
+.main,
+.content {
+  min-width: 0;
+}
+
+.highlight pre {
+  border: 1px solid var(--color-background-border);
+  border-radius: 0.3rem;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+
+table.docutils {
+  box-shadow: none;
+  border: 1px solid var(--color-background-border);
+}
+
+article > .image-reference {
+  float: right;
+  width: 13rem;
+  max-width: 32%;
+  margin: 0 0 1.5rem 1.5rem;
+}
+
+article > .image-reference > img {
+  width: 100%;
+  margin: 0;
+}
+
+#dohnuts > h1 {
+  font-size: clamp(2.75rem, 6vw, 4.5rem);
+  margin-bottom: 0.25rem;
+}
+
+#dohnuts > h1 + p {
+  font-size: 1.5rem;
+  margin-top: 0;
+}
+
+#dohnuts > section {
+  clear: both;
+}
+
+@media (max-width: 40rem) {
+  article > .image-reference {
+    width: 5.5rem;
+    margin-left: 0.75rem;
+  }
+}

docs/conf.py

@@ -0,0 +1,66 @@
+"""Build the static website from the repository's existing Markdown."""
+
+from pathlib import Path
+import tomllib
+
+
+metadata = tomllib.loads((Path(__file__).parents[1] / "pyproject.toml").read_text())
+project = "Dohnuts"
+release = metadata["project"]["version"]
+language = "en"
+
+extensions = ["myst_parser"]
+root_doc = "index"
+include_patterns = [
+    "index.md",
+    "MODEL_CARD.md",
+    "docs/*.md",
+    "docs/figures/README.md",
+    "results/README.md",
+]
+exclude_patterns = ["docs/naming-and-writing.md", "docs/versioning.md"]
+myst_enable_extensions = ["html_image"]
+myst_heading_anchors = 4
+
+html_theme = "furo"
+html_title = project
+html_logo = "../assets/dohnuts-logo.png"
+html_favicon = html_logo
+html_static_path = ["_static"]
+html_css_files = ["brand.css"]
+html_show_sourcelink = False
+html_copy_source = False
+html_domain_indices = False
+html_use_index = False
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "source_repository": "https://github.com/PsiACE/dohnuts/",
+    "source_branch": "main",
+    "source_directory": "",
+    "light_css_variables": {
+        "color-brand-primary": "#A52A60",
+        "color-brand-content": "#A52A60",
+        "color-brand-visited": "#A52A60",
+        "color-foreground-primary": "#38241F",
+        "color-foreground-secondary": "#66544D",
+        "color-foreground-muted": "#66544D",
+        "color-background-primary": "#FFF9F4",
+        "color-background-secondary": "#F8F0EA",
+        "color-background-hover": "#FBE8EF",
+        "color-background-border": "#E5D8CF",
+        "color-highlight-on-target": "#FBE8EF",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#FF9BC0",
+        "color-brand-content": "#FF9BC0",
+        "color-brand-visited": "#FF9BC0",
+        "color-foreground-primary": "#FFF9F4",
+        "color-foreground-secondary": "#D2BFB5",
+        "color-foreground-muted": "#C7B2A8",
+        "color-background-primary": "#241B18",
+        "color-background-secondary": "#302420",
+        "color-background-hover": "#47302F",
+        "color-background-border": "#59453D",
+        "color-highlight-on-target": "#47302F",
+    },
+}

docs/design.md

@@ -1,5 +1,15 @@
 # Model architecture
 
+```{toctree}
+:hidden:
+
+RLCD <rlcd>
+Compute efficiency <compute-efficiency>
+Data and evaluation <data-and-evaluation>
+Reference protocols <upstream-alignment>
+Benchmarking <local-benchmarks>
+```
+
 Dohnuts accepts a state and independent questions and returns temperature-scaled
 probabilities over supplied candidates. The training and serving templates are
 shared. A request reuses its causal prefix and computes question suffixes in

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==9.1.0
+furo==2025.12.19
+myst-parser==5.1.0

docs/website.md

@@ -0,0 +1,32 @@
+# Build the website
+
+The static website uses Sphinx, Furo, and MyST. Sphinx builds the pages and
+search index, Furo supplies navigation and responsive layouts, and MyST reads
+the existing Markdown. The site uses the README, model card, guides, and saved
+figures directly; do not maintain separate copies of their content.
+
+From the repository root, with Python 3.12 or newer:
+
+```bash
+python -m venv .cache/site-venv
+.cache/site-venv/bin/python -m pip install -r docs/requirements.txt
+.cache/site-venv/bin/python -m sphinx -b html -W --keep-going -d build/doctrees -c docs . build/site
+.cache/site-venv/bin/python -m http.server 8000 --directory build/site
+```
+
+Open `http://localhost:8000`. The generated files are in `build/site`.
+The build installs only documentation dependencies. It does not import Dohnuts,
+execute the examples, load models, train, or download datasets.
+
+Keep navigation in the existing MyST `toctree` directives. Use `docs/conf.py`
+for theme settings and `docs/_static/brand.css` for small styling changes.
+Keep the existing logo and published figures as the visual sources.
+
+## GitHub Pages
+
+The website workflow builds pull requests without publishing. Pushes to `main`
+and manual runs on `main` build and deploy the static output to GitHub Pages.
+Set the repository's Pages source to **GitHub Actions** before the first deploy.
+The deployment uses the repository's `github-pages` environment and respects any
+configured protection rules. It requires no custom server, external hosting
+account, or repository secret.

index.md

@@ -0,0 +1,15 @@
+---
+hide-toc: true
+---
+
+```{include} README.md
+```
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+Models <MODEL_CARD>
+Documentation <docs/README>
+Research <docs/design>
+```