50Ω – svensk adaption

Generator för en svensk webbplats för självstudier inför Instegscertifikatet och HAREC. Projektet är en oberoende svensk adaption av 50ohm.de och drivs varken av DARC e.V. eller av SSA.

Licens, attribution och ändringsmeddelande

Det här repot är baserat på generatorn bakom 50ohm.de (DARC e.V.), originalet finns i repot DARC-e-V/50ohm (grenen main). Generatorns kod är licensierad under AGPL-3.0 (se LICENSE); innehållet på 50ohm.de är licensierat under CC BY 4.0 och måste tillskrivas DARC e.V. Licensfilerna ska behållas.

Ändringar: Generatorn har översatts till svenska (gränssnitt, bildtexter, LaTeX, enhets- och typografiregler enligt svensk praxis), kurserna har ersatts av Instegscertifikat, HAREC och uppgradering från Instegscertifikat till HAREC, den tyska frågebanken är valfri, och all DARC-/tysk branding och alla länkar till tyska tjänster har tagits bort.

Detta är en oberoende adaption. Den är inte godkänd av DARC eller SSA.

Översikt

Utbildningsmaterialet skrivs i ett utökat markdown-format, internt kallat DARCdown. Kärnan i generatorn är en parser baserad på mistletoe som har utökats med extra syntax och utdataformat. Formatet beskrivs i README-FORMAT.md i innehållsrepot.

Utdataformat:

• HTML: fifty_ohm_html_renderer.py
• LaTeX: fifty_ohm_latex_renderer.py
• HTML för presentationer med reveal.js: fifty_ohm_html_slide_renderer.py

Själva generatorn finns i src, framför allt skriptet build.py. Namnen på webbplatsens sidor definieras på ett ställe: src/pages.py.

Kurser (Edition)

Tre kurser byggs. Varje kurs har en innehållsförteckning (toc) i innehållsrepot:

Edition (--edition)	Kurs	Fil
INSTEG	Instegscertifikat	toc/INSTEG.json
HAREC	HAREC	toc/HAREC.json
UPPGRADERING	Uppgradering: Instegscertifikat till HAREC	toc/UPPGRADERING.json

Utan --edition byggs alla tre. Alternativet kan anges flera gånger:

$ python main.py --edition INSTEG --edition HAREC

Innehållsrepot

Generatorn läser sitt innehåll från ett separat repo med följande struktur:

toc/<EDITION>.json                 innehållsförteckning per kurs
contents/sections/<ident>.md       text för ett avsnitt
contents/slides/<ident>.md         presentation för ett avsnitt (valfri)
contents/snippets/*.md             korta texter för startsidan
contents/static/<sida>.html        statiska sidor (+ <sida>_sidebar.html, valfri)
contents/drawings, photos, html    bilder, foton och inbäddad HTML
contents/questions/question_pool.json   frågebank (valfri, se nedan)
contents/questions/metadata.json        bildmetadata för frågorna (valfri)
contents/solutions/<frågenummer>.md     lösningsvägar (valfria)

Statiska sidor och snippets

Följande sidnamn används (se src/pages.py): prov, info, sok, kurser_karta, kurser_lista, mentorer. För de tre sista används en generell mall om innehållsrepot saknar motsvarande statiska sida. Saknade snippets ger tom text, bygget misslyckas inte.

Snippets som används på startsidan: index_title, index_teaser, index_content, index_btn_start, index_btn_vad_ar_amatorradio, lernen_selbst_title, lernen_selbst_teaser, lernen_selbst_btn_instegs, lernen_selbst_btn_harec, lernen_selbst_btn_uppgradering, lernen_kurs_* och lernen_mentor_* (title, teaser, btn).

Frågebank (valfri)

Det finns ingen svensk frågebank. Om contents/questions/question_pool.json saknas hoppar generatorn över provsimulatorn, övningsverktyget, lösningssidorna och question_index.json, och alla länkar dit döljs i mallarna (Jinja-variabeln has_question_pool). Finns frågebanken byggs allt som förut. metadata.json är valfri; saknas en fråga där används standardvärden.

Kom igång

Installera Python och beroenden

Projektet är uppsatt med uv men fungerar lika bra med pip och venv. Använd Python-versionen i .python-version.

$ uv venv
$ source .venv/bin/activate
$ uv pip sync requirements.txt

Med venv och pip:

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

Bygga

Ange sökvägen till ett utcheckat innehållsrepo, antingen i config/config.json (se config/config.json.example), som miljövariabel OHM_INPUT eller på kommandoraden:

$ python main.py -i ../50ohm-contents-dl -o build

Flaggor: --input/-i (innehåll), --output/-o (målkatalog, standard ./build), --edition (kurs, se ovan), --no-render-editions, --no-render-solutions, --build-zip. python build.py bygger allt och packar build/build.zip.

Testa lokalt

Startsidan är build/index.html. För att sökfunktionen ska fungera krävs en lokal webbserver:

$ cd build/
$ python3 -m http.server 8000

Öppna sedan http://localhost:8000/index.html.

Hosting

Resultatet är rent statiska filer. Kopiera innehållet i build/ till valfri webbserver (nginx, Apache, GitHub Pages, ...). Alla länkar är relativa. Ett Docker-bygge finns i docker/Dockerfile:

$ docker build -f docker/Dockerfile -t 50ohm-sv .
$ docker run --rm -v ../50ohm-contents-dl:/content -v $PWD/build:/build 50ohm-sv -i /content -o /build

Webbplatsens sidfot innehåller en platshållare för driftansvarigs egna utgivar-/kontaktuppgifter och integritetspolicy (templates/html/page.html, markerad med TODO). Den måste fyllas i innan webbplatsen publiceras.

Tester och kodstil

$ pip install pytest ruff
$ python -m pytest
$ ruff check . && ruff format --check .

Presentationer

Se doc/Slides.md.