Merge pull request #1 from BeeHive-org/docs-rework-zensical

Rework docs: migrate to Zensical, ingredients/recipes structure, real code & BOMs

Author: amchagas

.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Allow the workflow to publish to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One Pages deployment at a time; let an in-progress one finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      # `poe build` regenerates the Ingredients catalogue from data/ then runs
+      # `zensical build` into ./site.
+      - name: Build site
+        run: uv run poe build
+
+      - 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

.github/workflows/docs.yml

@@ -1,4 +1,11 @@
 # Files generated by build
 /site
+.cache/
+
+# Python / uv
+.venv/
+__pycache__/
+
+# Editor / OS
 *.vscode
 *.DS_Store

.gitignore

@@ -1,5 +1,48 @@
 <p align="center">
-  <img src="material/assets/images/beehive_logo.png">
+  <img src="docs/assets/logo.png" width="160">
 </p>
 
-# BeeHive
+# BeeHive documentation
+
+The documentation site for [BeeHive](https://github.com/BeeHive-org/BeeHive) —
+a flexible open electronics platform for building research equipment and
+teaching electronics.
+
+Built with [Zensical](https://zensical.org/) and managed with
+[uv](https://docs.astral.sh/uv/).
+
+## Develop
+
+```bash
+uv sync              # install dependencies
+uv run poe serve     # live-reload preview at http://127.0.0.1:8000
+uv run poe build     # build the static site into ./site
+uv run poe gen       # regenerate the Ingredients catalogue from docs/data/ingredients/
+uv run poe sync      # refresh the vendored board BOMs from the BeeHive repo
+```
+
+`serve` and `build` run `gen` first, so the auto-generated
+[Ingredients catalogue](docs/ingredients/index.md) always mirrors the YAML in
+[`docs/data/ingredients/`](docs/data/ingredients/).
+
+Board bills-of-materials are pulled from the BeeHive hardware repo's
+`kitspace.yaml` and **vendored** into [`docs/data/kitspace/`](docs/data/kitspace/)
+so builds stay offline. Run `uv run poe sync` occasionally (and commit the
+result) to refresh them; `gen` reads the vendored copy and never needs the
+network.
+
+## Structure
+
+Everything the site needs lives under `docs/`, so it can be dropped into another
+repository as a self-contained folder:
+
+- `docs/` — the Markdown pages (`ingredients/*.md` is **generated** — don't edit
+  by hand).
+- `docs/data/ingredients/` — the board catalogue, single source of truth (YAML).
+- `docs/data/kitspace/` — vendored board BOMs (from `uv run poe sync`).
+- `docs/scripts/build_ingredients.py` — generates the Ingredients pages.
+- `docs/scripts/sync_kitspace.py` — refreshes the vendored BOMs.
+- `zensical.toml` — site config, theme, and navigation.
+- `docs/stylesheets/extra.css` — the "bumblebee" pixi.sh-style layout.
+
+See [Contributing](docs/contributing.md) for how to add boards and recipes.

README.md

@@ -0,0 +1,62 @@
+---
+title: AI use policy
+description: How to use AI tools when contributing to BeeHive — you are accountable for what you submit.
+---
+
+# AI use policy
+
+BeeHive welcomes contributions made with the help of AI tools — but **you are
+responsible for everything you submit**. This page sets out how to use them well.
+
+## The core principle
+
+We are humans who enjoy working with other humans. Use whatever tools help you,
+but you are ultimately accountable for the boards, code, and documentation you
+contribute. If you would not be comfortable explaining a change and standing
+behind it, it is not ready to submit.
+
+## Please don't
+
+- Let an AI agent open pull requests on your behalf.
+- Submit a board design, recipe, code, or docs change you have not personally
+  understood and tested.
+- Let a chatbot carry on a conversation (an issue thread, a PR review) for you.
+
+Pull requests that appear to ignore these guidelines may be closed without
+review — checking un-vetted machine output costs maintainers more time than it
+saves.
+
+## Using AI to build and code
+
+- **Get familiar with what you are changing first.** Understanding the board,
+  the [design rules](introduction/design-rules.md), or the code you are touching
+  lets you write better prompts *and* judge whether the output is right.
+- **Don't trust an assistant's claims about how BeeHive works.** LLMs are often
+  confidently wrong, even about things the docs answer directly. Check against
+  the design rules, the board's schematics, or a real device.
+- **Test on hardware.** A recipe or snippet that looks plausible is not a
+  contribution until it actually runs on the boards it claims to.
+- **Keep pull requests small and focused,** even if a tool generated everything
+  in one go. One board, one recipe, or one fix per PR is far easier to review.
+- **Edit AI-written comments and prose.** Prefer clarity and brevity over
+  exhaustive, generic text; delete comments that just restate the code.
+
+## Using AI to communicate
+
+- **Say why, not what.** A PR description that merely restates the diff adds
+  nothing — explain your reasoning and what you tested.
+- **Fill in the templates yourself.** Issue and PR templates exist to save
+  everyone time; complete them rather than having a tool do it.
+- **Verify anything you post.** Don't paste unchecked AI output into an issue or
+  a pull request.
+- **Link, don't quote.** Pointing to the primary source — a datasheet, the docs,
+  a repo file — beats quoting an LLM. If you must quote one, put it in a
+  `>` blockquote so it is clearly machine output, not your own words.
+- **Clarity over polish.** A clear, slightly imperfect message beats a
+  perfectly-worded one that hides the point.
+
+## Attribution
+
+This policy is adapted from the
+[napari AI use policy](https://napari.org/dev/developers/contributing/ai.html),
+which was itself adapted from Zulip's AI usage guidelines.

docs/ai-use-policy.md

@@ -0,0 +1,60 @@
+---
+title: Contributing
+description: How to contribute boards, recipes, and fixes to BeeHive.
+---
+
+# Contributing
+
+BeeHive is open source and community-driven. Contributions aren't confined to
+one institution — anyone can add a board, share a recipe, or improve the docs.
+
+!!! note "Using AI tools?"
+    That's fine — but you're accountable for what you submit. Please read the
+    [AI use policy](ai-use-policy.md) first.
+
+## Ways to contribute
+
+- 🧩 **A new board (ingredient).** Design a daughter board that follows the
+  [design rules](introduction/design-rules.md) and share it. See
+  [Build your own board](techniques/build-your-own-board.md).
+- 🍯 **A new recipe.** Built an instrument with BeeHive? Document it as a recipe
+  so others can reproduce it — especially outside neuroscience.
+- 🐛 **Fixes & improvements.** Corrections to boards, code, or these docs are all
+  welcome.
+
+## Adding a board to the catalogue
+
+The [Ingredients catalogue](ingredients/index.md) is generated from YAML — you
+don't edit the page directly:
+
+1. Add an entry to `docs/data/ingredients/boards.yaml` (or drop in a new
+   `docs/data/ingredients/<board>.yaml`).
+2. Run `uv run poe gen` to regenerate the catalogue.
+3. Preview with `uv run poe serve`.
+
+See the comments at the top of `boards.yaml` for the field reference. If the
+board has a project in the [BeeHive repo's](https://github.com/BeeHive-org/BeeHive)
+`kitspace.yaml`, add its `kitspace:` key too — `uv run poe sync` then vendors the
+board's bill of materials and fabrication-file links into the catalogue.
+
+## Editing the docs
+
+The docs are a [Zensical](https://zensical.org/) site managed with
+[uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync                 # install dependencies
+uv run poe serve        # live-reload preview at http://127.0.0.1:8000
+uv run poe build        # build the static site into ./site
+```
+
+`serve` and `build` regenerate the Ingredients catalogue first, so it always
+matches the YAML.
+
+## Get in touch
+
+- Issues & discussion:
+  [github.com/BeeHive-org/BeeHive/issues](https://github.com/BeeHive-org/BeeHive/issues)
+- Email: [a.maia-chagas@sussex.ac.uk](mailto:a.maia-chagas@sussex.ac.uk)
+
+If in doubt — reach out. We're glad to help.