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>
46 lines
1.2 KiB
YAML
46 lines
1.2 KiB
YAML
name: Build docs site
|
|
|
|
on:
|
|
push:
|
|
branches: [main]
|
|
pull_request:
|
|
branches: [main]
|
|
workflow_dispatch:
|
|
|
|
jobs:
|
|
build:
|
|
runs-on: self-hosted
|
|
container:
|
|
image: python:3.13-bookworm
|
|
volumes:
|
|
- /srv/docs-makerfloss/html:/output
|
|
steps:
|
|
- name: Install git for actions/checkout
|
|
run: |
|
|
apt-get update -qq
|
|
apt-get install -y --no-install-recommends git rsync
|
|
|
|
- name: Checkout repository
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Install Python dependencies
|
|
run: pip install --quiet -r requirements.txt
|
|
|
|
- name: Regenerate hardware index
|
|
run: python3 scripts/gen_overview.py --category hardware
|
|
|
|
- name: Fail on drift in docs/hardware/index.md
|
|
run: |
|
|
if ! git diff --exit-code docs/hardware/index.md; then
|
|
echo
|
|
echo "::error::docs/hardware/index.md is stale."
|
|
echo "Regenerate locally via 'make docs-index' and commit the result."
|
|
exit 1
|
|
fi
|
|
|
|
- name: Build site (strict)
|
|
run: mkdocs build --strict
|
|
|
|
- name: Publish to /output (main only)
|
|
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
|
|
run: rsync -a --delete site/ /output/
|