BeeHive-org · roaldarbol · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.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
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,11 @@
 # Files generated by build
 /site
+.cache/
+
+# Python / uv
+.venv/
+__pycache__/
+
+# Editor / OS
 *.vscode
 *.DS_Store
diff --git a/README.md b/README.md
@@ -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.
diff --git a/docs/ai-use-policy.md b/docs/ai-use-policy.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.
diff --git a/docs/assembly-guide.md b/docs/assembly-guide.md
diff --git a/docs/assets/apple-touch-icon.png b/docs/assets/apple-touch-icon.png
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
diff --git a/docs/contributing.md b/docs/contributing.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.
diff --git a/docs/courses/intro-to-electronics/friday.md b/docs/courses/intro-to-electronics/friday.md
@@ -0,0 +1,26 @@
+---
+title: Friday
+description: Sketching your own protocols and building a project.
+---
+
+# Friday
+
+Time to sketch your own protocols! Our suggestion is to start with a mockup of your project/need, in other words, think about in general terms of steps needed to be taken for your software/project to be up and running. Example for the reaction time task we created:
+
+
+
+1. Inter trial interval (random?)
+2. LED comes on
+3. Start counting time until button is pressed
+4. Detect button press
+5. Turn led off
+6. Record time elapsed
+7. Start next trial
+* Take the next XX minutes to think about and write down the steps for your task.
+* Now, show your sketch to the person next to you! While they are reading yours, take a moment to read theirs and make comments! Can you see if something is missing? Is there something that is not clear to you?
+
+Time to implement your task using the training board! 
+
+
+
+* Using the training board, start writing actual code to implement your task. Preferably, it needs to be connected to your subject area and achieve a goal that you have set. One of the most time-effective ways to do that is to write small parts of the code and test often to see if the board and code are reacting the way you would expect them to react. But first, create a sketch-diagram showing how your code is supposed to work
diff --git a/docs/courses/intro-to-electronics/glossary.md b/docs/courses/intro-to-electronics/glossary.md
@@ -0,0 +1,38 @@
+---
+title: Glossary
+description: Key terms from the electronics course.
+---
+
+# Glossary
+
+**Microcontroller** - a small computer made on an integrated circuit
+
+**Integrated circuit** - a tiny chip that contains a lot of components (resistors, transistors, capacitors) that are all electrically connected together and work together to reach a certain goal (compare or amplify signals, rectification, etc.)
+
+**Central processing unit** - An electronic circuit on chip which executes instructions
+
+**Nonvolatile memory** - a type of computer memory that can retain stored information even after power is removed
+
+**Volatile memory** - a type of computer memory that loses information after power is removed
+
+**Internet of Things (IoT)** - Sensors, electronic devices and actuators that are comprised in one system which sends, receives and process information from the said elements with a help of network
+
+**Shift register** - IC that allows to control multiple elements via saving the output in the register
+
+**Logic level** - voltage value that is high enough to be recognised by a microcontroller as 1, or logic HIGH, usually 3.3 V or 5V.
+
+**Pulse-Width Modulation (PWM)** - a signal that consist of logic HIGH and logic LOW pulses at a certain frequency. Duration of logic HIGH pulse determines PWM duty cycle which consequently is the percentage of power that the signal carries.
+
+**Bit** - it can either be 0 or 1, a single cell that contains binary data. The fundamental piece of information storage.
+
+**Byte** - 8 bits
+
+**Word** - 2 bytes
+
+**Object oriented programming** - a programming paradigm based on use of objects and classes.
+
+**To compile code** - a compiler is a software that translates high-level programming language to machine code which can be executed
+
+**Analog-to-digital converter **- a circuitry that recreates arbitrary analog signal with digital code, accuracy of which depends on converter’s resolution
+
+**Baud rate **- the rate of information transmission
diff --git a/docs/courses/intro-to-electronics/index.md b/docs/courses/intro-to-electronics/index.md
@@ -0,0 +1,18 @@
+---
+title: Intro to Electronics
+description: A project-based introduction to microcontrollers, circuits, and MicroPython, over a week.
+---
+
+# Intro to Electronics
+
+This course introduces microcontrollers, basic electronics, and MicroPython
+from the ground up. It comes with code from BeeHive's [2022 workshop](https://github.com/BeeHive-org/BeeHive/tree/master/workshops/2022_autum/code).
+
+It's organised as a week of hands-on days:
+
+- **[Monday](monday.md)** — microcontrollers, Ohm's Law, and first steps in Python/MicroPython
+- **[Tuesday](tuesday.md)** — timers and counters
+- **[Wednesday](wednesday.md)** — data logging
+- **[Thursday](thursday.md)** — putting BeeHive boards together
+- **[Friday](friday.md)** — sketching your own protocols
+- **[Glossary](glossary.md)** — key terms