docs: add mdbook site sourced from existing markdown docs

Author: collinsezedike

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "book/**"
+      - "README.md"
+      - "CONTRACT.md"
+      - "INTEGRATION.md"
+      - "CONTRIBUTING.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: "latest"
+
+      - name: Build book
+        run: mdbook build book
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: book/book
+
+  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

@@ -1 +1,2 @@
 /target
+/book/book

CONTRIBUTING.md

@@ -78,6 +78,17 @@ There are two layers, and they catch different things:
   a storage key without either handling the "missing" case explicitly or having a
   preceding check in the same function that guarantees it exists.
 
+## Docs site
+
+`book/` is an [mdBook](https://rust-lang.github.io/mdBook/) that publishes this
+repo's markdown docs as a site, deployed automatically from `main` by
+`.github/workflows/docs.yml`. It does not contain its own content: `book/src/*.md`
+files are one-line `{{#include}}`s pointing at the real files at the repo root
+(`README.md`, `CONTRACT.md`, `INTEGRATION.md`, this file), so there's a single
+source of truth. Edit the root file, not the file under `book/src/`.
+
+Preview locally with `mdbook serve book` (requires `cargo install mdbook`).
+
 ## Before opening a PR
 
 Run the same checks CI runs, in this order (see the note above on why the wasm

book/book.toml

@@ -0,0 +1,10 @@
+[book]
+title = "Tholos"
+description = "Bonded assertion and dispute oracle for resolving real world outcomes"
+authors = ["drydocs"]
+language = "en"
+src = "src"
+
+[output.html]
+git-repository-url = "https://github.com/drydocs/tholos"
+edit-url-template = "https://github.com/drydocs/tholos/edit/main/book/{path}"

book/src/CONTRACT.md

@@ -0,0 +1 @@
+{{#include ../../CONTRACT.md}}

book/src/CONTRIBUTING.md

@@ -0,0 +1 @@
+{{#include ../../CONTRIBUTING.md}}

book/src/INTEGRATION.md

@@ -0,0 +1 @@
+{{#include ../../INTEGRATION.md}}

book/src/README.md

@@ -0,0 +1 @@
+{{#include ../../README.md}}

book/src/SUMMARY.md

@@ -0,0 +1,7 @@
+# Summary
+
+[Introduction](README.md)
+
+- [Contract Reference](CONTRACT.md)
+- [Integration Guide](INTEGRATION.md)
+- [Contributing](CONTRIBUTING.md)