Skip to content

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

Open
roaldarbol wants to merge 14 commits into
mainfrom
docs-rework-zensical
Open

Rework docs: migrate to Zensical, ingredients/recipes structure, real code & BOMs#1
roaldarbol wants to merge 14 commits into
mainfrom
docs-rework-zensical

Conversation

@roaldarbol

@roaldarbol roaldarbol commented Jul 15, 2026

Copy link
Copy Markdown
Collaborator

Major rework of the BeeHive documentation.

Toolchain & design

  • Migrate MkDocs → Zensical, managed with uv (poethepoet tasks: serve/build/gen/sync).
  • pixi.sh / Croppy-style layout with a bumblebee (amber + black) palette; new transparent, centred logo/favicon/apple-touch icons (rebuilt from the source so the enclosed crossbar is preserved).
  • GitHub Pages deploy workflow (uv + Zensical) replacing mkdocs gh-deploy.

Structure (ingredients & recipes)

  • New IA: Introduction, Ingredients (overview + per-category pages), Techniques, Recipes, Courses, Contributing.
  • Data-driven Ingredients catalogue: single source of truth in docs/data/ingredients/*.yaml → docs/scripts/build_ingredients.py generates the pages.
  • Kitspace integration: uv run poe sync vendors each board's BOM from the hardware repo's kitspace.yaml; boards show a collapsible Bill of materials + "Order & BOM on Kitspace" / gerbers / KiCad links.
  • Recipes: two-table ingredients (BeeHive boards + other components); a Write your own recipe guide.
  • data/ and scripts/ live under docs/ so the site is a self-contained folder.

Content

  • Finished/rewrote the stub, placeholder and duplicated pages; added the Training board.
  • Recipe code grounded in real repo sources where it exists (5-CSRTT, solenoid-driver examples); the rest clearly flagged Illustrative — not published upstream.
  • Electronics course: cleaned the gd2md paste, wired up arithmatex + MathJax (incl. an instant-navigation fix), tidied formulas, capitalised "Intro to Electronics", and split into per-day pages (Mon–Fri + Glossary).
  • Audited all 124 external links; fixed the broken ones (KineMouse, LI-850, Pinecil).

Preview locally with uv run poe serve.

🤖 Generated with Claude Code

roaldarbol and others added 12 commits July 15, 2026 12:37
@roaldarbol @claude
Rework docs: migrate to Zensical + uv, add ingredients/recipes structure
f96c870 
Migrate the documentation from MkDocs Material to Zensical, managed with uv
(poethepoet tasks), mirroring the Croppy/pixi.sh design with a "bumblebee"
amber+black palette.

- Data-driven Ingredients catalogue: data/ingredients/*.yaml is the single
  source of truth; scripts/build_ingredients.py generates docs/ingredients/
  index.md (14 boards) before serve/build.
- New information architecture: Introduction (what-is-beehive, getting-started,
  design-rules), Ingredients, Techniques (soldering, micropython,
  build-your-own-board), Recipes (8 pages drafted from the RSOS paper), Courses,
  Contributing.
- Replace/finish stub, placeholder, and duplicated pages; clean the gd2md
  banner from the electronics course.
- Retire mkdocs.yml and material/; add pyproject.toml, zensical.toml, uv.lock,
  and the bumblebee stylesheet.

Recipe schematics, per-board BOMs, and some daughter boards remain TODO
(marked in-file).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Polish docs: fix icons/arrows, split Ingredients, new logo, deploy wo…
27b4bdb 
…rkflow

- Replace unrendered :material-* icon shortcodes with emoji; remove "->"/"→"
  arrows from prose and wiring lists per feedback.
- Drop dev-targeted info box from the generated Ingredients page.
- Split Ingredients into an overview + one page per category; rename the
  ambiguous "control" category to "Utilities"; generator now emits per-category
  pages and recipe cross-links point at ../ingredients/<category>.md#<slug>.
- Add the Training board to the catalogue under a new "Training" category.
- Add a "Write your own recipe" guide and link it from the Recipes overview.
- New logo: key out the dark background (preserving the yellow crossbar the
  old removal deleted), centre the mark, and generate logo/favicon/apple-touch
  icons; point config + stylesheet at logo.png; drop the old SVG.
- Replace the MkDocs gh-deploy CI with a uv + Zensical GitHub Pages workflow.
- Dedupe the home <title> ("Open electronics for research - BeeHive").

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Render course LaTeX math: wire up arithmatex + MathJax in Zensical
7936078 
The MkDocs MathJax config didn't carry over, so the course's $$...$$ formulas
rendered as literal text. Enable pymdownx.arithmatex (generic mode) and load
MathJax (config in javascripts/Mathjax.js + the tex-mml-chtml CDN) via
extra_javascript. Drop the unused tables.js left over from the old tablesort.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Tidy course formulas: wrap word variables in \text, subscript symbols
db8cf7c 
Multi-word variables (Sample Rate, Frequency, Nyquist frequency) and
units (ticks/tock, tock, ms, µs) now use \text so MathJax stops
italicising them letter-by-letter; fs and fNyquist/fMax become proper
subscripts (f_s, f_Nyquist, f_max); the * multiplier becomes \times.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Integrate kitspace.yaml: vendor board BOMs into the Ingredients catal…
5466fa9 
…ogue

Add `uv run poe sync` (scripts/sync_kitspace.py) which fetches the BeeHive
hardware repo's kitspace.yaml and every board's 1-click-bom.csv and vendors
them into data/kitspace/ (committed, so builds stay offline/reproducible).

Each board in boards.yaml gains an optional `kitspace:` key mapping to a
manifest project; the generator then renders, per board, a "Hardware files"
line (full BOM, gerbers, KiCad PCB on GitHub) and a collapsible Bill of
materials (Ref / Qty / Description) — 9 boards covered. Restore the "µ" lost
to an upstream encoding slip in the "33µH" inductor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Recipes: split ingredients into board + component tables; add Kitspac…
dd99708 
…e links

- Every recipe's Ingredients section now has two labelled tables: "BeeHive
  boards" and "Other components" (Component / Qty / Notes), replacing the old
  prose parts list; the write-your-own template matches. Move the off-the-shelf
  DRV8833 out of the mouse-wheel boards table.
- Ingredients overview: drop the near-empty "Size" column from the at-a-glance
  table (size still shown on the board detail where set).
- Board pages now link "Order & BOM on Kitspace" (interactive BOM + one-click
  ordering) as the primary hardware link, alongside gerbers and the KiCad PCB.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Move data/ and scripts/ under docs/ for portability
1d21fec 
Relocate data/ -> docs/data/ and scripts/ -> docs/scripts/ so the whole site is
a self-contained folder that can drop into another repo (e.g. the main BeeHive
repo). Update the poe tasks, script ROOT paths (OUT_DIR now docs/ingredients),
generated-file banner, workflow path filters, README, contributing, and the
boards.yaml header accordingly. Zensical has no exclude mechanism, so the
vendored data + scripts are served as static files — harmless (open source), and
the BOM CSVs become downloadable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Ground recipe code in real repo sources; flag the rest as illustrative
200f73b 
Replace fabricated code snippets with real, linked code from the BeeHive repos
where it exists, and clearly mark the remainder as illustrative:

- 5-CSRTT: real IR-sensor / cue-LED / servo-dispenser code (actual pins) from
  BeeHive-org/5-choice-serial-reaction-time, linking the full paradigm.
- head-fixed-reward, odour-stimulator, LI-850: real solenoid-driver example from
  the BeeHive repo for valve control; rig-specific timing / serial-polling
  described honestly (LI-850's serial layer marked ILLUSTRATIVE — not upstream).
- mouse-maze, mouse-wheel, openflexure: no matching upstream code — kept the
  illustrative sketches but added a prominent "Illustrative — not published
  upstream" warning and linked real related building blocks where they exist.

Also fix left-sidebar spacing so leaf and collapsible nav rows share the same
gap (spacing moved to the list item; container rows no longer double-pad).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Fix three broken external links
92654eb 
- KineMouse: github.com/G-Node/kinemouse (404) -> the canonical hackaday.io
  project page (mouse-wheel recipe, 2 links + could be referenced elsewhere).
- LI-850: licor.com/.../gas-analysis/LI-850 (404, LI-COR restructured) ->
  the current LI-830-LI-850 product page.
- Pinecil: pine64.org/pinecil/ (404) -> pine64.org/devices/pinecil/.

Verified all 124 external links; the rest resolve or are live sites that
block automated requests (allaboutcircuits, o'reilly, digikey, arrow) — those
are pre-existing course links.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Fix course equations rendering blank under instant navigation
4f05013 
The MathJax hook called MathJax.typesetPromise() on document$'s first emission,
which fires before the MathJax library script has loaded. That threw
(typesetPromise undefined) and RxJS tore the subscription down, so any page
reached via instant navigation — including the electronics course — never got
re-typeset and its formulas rendered blank.

Guard the callback so the pre-load emission is a no-op (first render is handled
by MathJax's own startup), and add the standard clearCache/typesetClear/texReset
before re-typesetting on later navigations.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Course: capitalise "Intro to Electronics"; split into per-day pages
fc0300b 
Split the single course page into a section with an overview plus one page per
day (Monday–Friday) and a Glossary, under courses/intro-to-electronics/:

- Monday: microcontrollers, Ohm's Law, Python/MicroPython (former Parts one–three)
- Tuesday: timers and counters
- Wednesday: data logging
- Thursday: putting BeeHive boards together
- Friday: sketching your own protocols
- Glossary

Fix image paths (../assets -> ../../assets) for the deeper pages, capitalise the
course name everywhere (nav, titles, prose links), and repoint every
cross-reference to the new overview page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Course: fix merged Ohm's Law equation on the Monday page
2715cfe 
Two adjacent $$...$$ blocks separated only by a bare 'and' (no blank lines)
were parsed as one math span, rendering '$$and$$' literally. Combine them into
a single formula with \quad\text{and}\quad.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol

roaldarbol commented Jul 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

@amchagas @isobianin Hey! I've made a large refactor of the docs, and finished things off with the help of Claude and the paper. A few things to note on top of the summary above:

  • Some of the code snippets are examples, not taken from any of the existing code as it doesn't seem to be available - at least in the BeeHive org. If it does exist, please point out where, then I can integrate it.
  • Some DBs are not on Kitspace yet. I've added links to the ones that are, but it would be awesome to have it for them all!

Other than that I think it is now in a much better state - but would be happy to hear some feedback! You can build locally with uv run poe serve.

Also let me know what you think, then I can merge afterwards - I need to change the Github Pages settings because the new Zensical/uv workflow works differently from how the docs are currently served.

roaldarbol and others added 2 commits July 15, 2026 17:29
@roaldarbol @claude
Reorder nav: Ingredients -> Recipes -> Techniques
83f66c6 
Keep the ingredients/recipes metaphor pair adjacent (Techniques previously
split them) and place the how-to-assemble Techniques after the builds.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@roaldarbol @claude
Add AI use policy page; recommend KiCad for board design
cf3d405 
- Add an AI use policy (adapted from napari's, itself from Zulip's), tailored to
  BeeHive contributions (boards, recipes, MicroPython, docs). Nest Contributing
  into a section (Overview + AI use policy) and link it from the Contributing page.
- "Build your own board": recommend KiCad (FOSS, and what BeeHive's boards use —
  open the existing .kicad_pcb files as references) plus FreeCAD for mechanical
  parts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@roaldarbol