From 62fcd8ac273147e6e6585452cc380f310aa73f4d Mon Sep 17 00:00:00 2001 From: sjat Date: Mon, 18 May 2026 17:13:50 +0200 Subject: [PATCH] docs: add proper README at repo root and per-tree READMEs - Rewrite the 84-byte Danish placeholder README.md into a proper English entry point: what this repo is, live URLs, layout, build instructions (make targets), and conventions, with pointers to CLAUDE.md for the long form. - Add short READMEs to notes/, sandbox/, and scripts/ so each tree documents its own purpose at the boundary where someone is likely to land on it via the Forgejo web UI or a clone. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++- notes/README.md | 8 +++++++ sandbox/README.md | 3 +++ scripts/README.md | 7 ++++++ 4 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 notes/README.md create mode 100644 sandbox/README.md create mode 100644 scripts/README.md diff --git a/README.md b/README.md index 4070ea1..124171d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,56 @@ # MakerFLOSS -Første midlertidige repo til Orange Makerspaces MakerFLOSS initiativ. \ No newline at end of file +Documentation and working notes for **MakerFLOSS**, an Orange Makerspace initiative — a bi-weekly FLOSS jam-session community focused on self-hosted, open-source infrastructure. + +- Live docs: +- Slides: +- Source: + +## Repository layout + +``` +docs/ # built into the public site (docs.makerfloss.eu) + hardware/ # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu) + infrastructure/ # labdesign, VPS/DNS, etc. + presentations/ # Marp decks (also published to slides.makerfloss.eu) +notes/ # repo-only working material — not part of the site + meetings/ # meeting notes (Danish allowed) + todo/ # task lists, working norms, wishlist, services + dev/ # internal plans/ and specs/ + communications/ # community comms artefacts +sandbox/ # scratch / pipeline fixtures +scripts/ # build helpers (hardware index, mkdocs hook) +``` + +## Building locally + +Requires Python 3.10+ and, for slide builds, either `marp` on `$PATH` or Docker. + +```bash +python3 -m venv .venv && source .venv/bin/activate +pip install -r requirements.txt +``` + +Common targets: + +```bash +make docs-serve # live-reload preview at http://127.0.0.1:8000 +make docs-build # strict build into ./site +make docs-index # regenerate docs/hardware/index.md from per-host frontmatter +make docs-check # CI drift-check for the hardware index +make slides # build Marp decks (docs/presentations/*.md) into ./slides +``` + +CI runs on the self-hosted Forgejo Actions runner (`.forgejo/workflows/docs.yml`) and rsyncs the built site to the VPS. + +## Conventions + +- **Filenames**: ASCII lowercase, kebab-case (`like-this.md`). Dated docs use `YYYY-MM-DD-label.md`. Hardware host pages are the exception — their filename stem must equal the `hostname` field, enforced by `scripts/gen_overview.py`. +- **Languages**: English for code and docs; Danish allowed in meeting notes and community communications. +- **Git**: Trunk-based, feature branches, simple commit messages, no secrets in commits. + +See [`CLAUDE.md`](CLAUDE.md) for the full working norms and AI-collaboration guidance. + +## License + +MIT — see [`LICENSE`](LICENSE). diff --git a/notes/README.md b/notes/README.md new file mode 100644 index 0000000..059cbcf --- /dev/null +++ b/notes/README.md @@ -0,0 +1,8 @@ +# notes/ + +Repo-only working material — meeting notes, todos, internal design docs, and community-communications artefacts. **Nothing here is built into the public site**; if you want a page to appear on , move it under `docs/`. + +- `meetings/` — meeting minutes (Danish allowed) +- `todo/` — task lists, working norms, wishlist, OM services +- `dev/` — internal plans and specs (pre-implementation thinking) +- `communications/` — Facebook posts and other community artefacts diff --git a/sandbox/README.md b/sandbox/README.md new file mode 100644 index 0000000..df9539a --- /dev/null +++ b/sandbox/README.md @@ -0,0 +1,3 @@ +# sandbox/ + +Scratch space and pipeline fixtures. Files here are kept around as test inputs (e.g. for the Marp/Mermaid slide pipeline) — they are not meant to be read as documentation. diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..4a648b3 --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,7 @@ +# scripts/ + +Build helpers for the documentation site. + +- `gen_overview.py` — generates a category index table from per-item YAML frontmatter (currently used for `docs/hardware/index.md`). Configured by `overview_config.yml`. Run via `make docs-index`; CI drift-checks it via `make docs-check`. +- `mkdocs_hooks.py` — MkDocs build hook that renders a Specs table on each hardware host page from its frontmatter, sharing `fmt_*` helpers with `gen_overview.py` so the host page and the index row stay in sync. +- `overview_config.yml` — schema (required fields, enums) and table layout for `gen_overview.py`.