6b1a61461b
Bootstraps an MkDocs Material documentation site (rendered to
docs.makerfloss.eu by the Forgejo Actions runner). The first feature
is an auto-generated hardware overview built from per-host YAML
frontmatter blocks under docs/hardware/.
- mkdocs.yml, requirements.txt: MkDocs Material 9.5 + pyyaml
- Makefile: docs-index | docs-build | docs-serve | docs-check
- scripts/gen_overview.py: stdlib + pyyaml generator, deterministic and
offline. Reads scripts/overview_config.yml — category-driven so
services/vms can plug in later without touching the script.
- scripts/overview_config.yml: hardware schema and index layout
- docs/hardware/{makerfloss,fisi,tembo}.md: 3 sample entries
- docs/hardware/index.md: GENERATED, committed (CI fails on drift)
- docs/index.md: site landing page
- .forgejo/workflows/docs.yml: drift-check + mkdocs build --strict +
rsync site/ to /srv/docs-makerfloss/html on push to main
- .gitignore: site/, .venv, __pycache__
Schema:
- hostname, kind, status (required; kind/status are enums)
- model, location, cpu, cpu_cores, cpu_threads, ram_gb, storage_gb,
storage_type (enum), storage_notes, nic_gbps (all optional)
- Filename stem MUST equal hostname (enforced by generator)
- Extra optional fields are accepted silently and live on the per-page
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
38 lines
1.2 KiB
YAML
38 lines
1.2 KiB
YAML
# Configuration for scripts/gen_overview.py
|
|
#
|
|
# Each top-level key is a category. The generator is invoked with
|
|
# --category <name> and looks up its block here. To add a new category
|
|
# (services, vms, ...) later, copy a block and adjust the fields.
|
|
|
|
hardware:
|
|
title: "Hardware Overview"
|
|
source_dir: docs/hardware
|
|
output_file: docs/hardware/index.md
|
|
required_fields:
|
|
- hostname
|
|
- kind
|
|
- status
|
|
enums:
|
|
kind: [server, laptop, sbc, switch, ap, desktop]
|
|
status: [in-use, spare, broken, donated]
|
|
storage_type: [nvme, ssd, hdd, mixed]
|
|
group_by: kind
|
|
# Human-friendly H2 names per group_by value. Anything missing falls back
|
|
# to the raw value title-cased + "s".
|
|
group_titles:
|
|
server: Servers
|
|
laptop: Laptops
|
|
sbc: Single-board computers
|
|
switch: Switches
|
|
ap: Access points
|
|
desktop: Desktops
|
|
sort_by: hostname
|
|
columns:
|
|
- { header: Hostname, kind: hostname-link }
|
|
- { header: Model, field: model }
|
|
- { header: Location, field: location }
|
|
- { header: CPU, kind: cpu }
|
|
- { header: RAM, kind: ram }
|
|
- { header: Storage, kind: storage }
|
|
- { header: NIC, kind: nic }
|
|
- { header: Status, field: status }
|