From caa904085d0e9d3960bcc723ad23ea1cba2c2ee0 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Tue, 22 Sep 2026 01:30:00 +0800 Subject: [PATCH] Add static documentation site --- .github/workflows/website.yml | 65 +++++++++++++++++++++++ MODEL_CARD.md | 13 +++-- README.md | 4 +- docs/README.md | 11 ++++ docs/_static/brand.css | 97 +++++++++++++++++++++++++++++++++++ docs/conf.py | 66 ++++++++++++++++++++++++ docs/design.md | 10 ++++ docs/requirements.txt | 3 ++ docs/website.md | 32 ++++++++++++ index.md | 15 ++++++ 10 files changed, 311 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/website.yml create mode 100644 docs/_static/brand.css create mode 100644 docs/conf.py create mode 100644 docs/requirements.txt create mode 100644 docs/website.md create mode 100644 index.md diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml new file mode 100644 index 0000000..d83a002 --- /dev/null +++ b/.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 diff --git a/MODEL_CARD.md b/MODEL_CARD.md index 63f2b3f..515f6c7 100644 --- a/MODEL_CARD.md +++ b/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 +Evaluation results +``` diff --git a/README.md b/README.md index 4b5b019..b91558c 100644 --- a/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index 21eab88..0108410 100644 --- a/docs/README.md +++ b/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 +Agent integration +Training and evaluation +Build the website +``` diff --git a/docs/_static/brand.css b/docs/_static/brand.css new file mode 100644 index 0000000..c588c51 --- /dev/null +++ b/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; + } +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a3fa0d4 --- /dev/null +++ b/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", + }, +} diff --git a/docs/design.md b/docs/design.md index cb3c6e2..0d1e1f6 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,5 +1,15 @@ # Model architecture +```{toctree} +:hidden: + +RLCD +Compute efficiency +Data and evaluation +Reference protocols +Benchmarking +``` + 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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..292f0da --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx==9.1.0 +furo==2025.12.19 +myst-parser==5.1.0 diff --git a/docs/website.md b/docs/website.md new file mode 100644 index 0000000..35a2865 --- /dev/null +++ b/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. diff --git a/index.md b/index.md new file mode 100644 index 0000000..f7f964f --- /dev/null +++ b/index.md @@ -0,0 +1,15 @@ +--- +hide-toc: true +--- + +```{include} README.md +``` + +```{toctree} +:hidden: +:maxdepth: 2 + +Models +Documentation +Research +```