2025-08-24_mkdocs_ny_struktur#

Detta dokument beskriver hur dokumentationssajten byggs, vilka delar som ingår (konfiguration, generator‑skript, frontend‑stöd), hur de samverkar och var dagens märkligheter/dupliceringar uppstår. Avslutningsvis ges konkreta förbättringsförslag för att göra lösningen robust och lättare att visa upp offentligt.

Översikt#

Byggsystem: MkDocs (Material‑tema) med anpassad layout via overrides/.
Källkodsvyer: Auto‑genererade Markdown‑sidor i docs/source/ som inkluderar riktiga filer via mkdocs-include-markdown-plugin.
Kommentarsystem: Separata kommentarfiler i docs/source_comments/ kopieras till build‑output och laddas dynamiskt av docs/javascripts/extra.js.
Output: Statisk sajt under site/, där både genererade källkodssidor (site/source/**) och kommentarfiler (site/source_comments/**) exponeras.

Konfiguration (mkdocs.yml)#

Nycklar och hur de påverkar bygget:

docs_dir: docs: allt källmaterial för dokumentation ligger under docs/.
theme.material.custom_dir: overrides: kundanpassade templates/layouts under overrides/ (relativt projektroten; MkDocs tolkar den relativt konfigurationsfilen).
plugins:
- include-markdown: injicerar innehåll från filer i sidor. Här konfigureras egna taggar opening_tag: '{!', closing_tag: '!}'.
- mkdocs-simple-hooks + on_post_build: scripts.mkdocs_hooks:copy_source_comments: kör en hook efter build som kopierar kommentarmappen.
hooks: - scripts/mkdocs_hooks.py: alternativ (inbyggt) hook‑stöd i MkDocs som definierar on_post_build i samma fil. Viktigt: både plugin‑hook och inbyggd hooks pekar till samma logik → körs sannolikt två gånger.
watch: - docs/source_comments: triggar ombyggnad när kommentarfiler ändras.
nav: manuellt kuraterad meny, idag rubricerad som “Source Code - ett par patchar efter:” med ett urval av källfiler under docs/source/**.

Generator‑skript och struktur#

scripts/generate_docs.py
- Skannar projektet (exkluderar docs/, site/, cache, m.m.), skapar för varje fil en wrapper‑sida i docs/source/…/*.md.
- Varje wrapper har formatet:
```
```<språk>
  {! include-markdown "<relativ/väg/till/filen>" !}
```
```
  - Detta gör att källfilens innehåll inkluderas i en kodblocksvy med syntaxhighlighting.
```
- Har stöd för att auto‑bygga en nav‑struktur och injicera en grupp kallad “Källkod:” i mkdocs.yml (via update_mkdocs_yml). Denna sektion finns inte i nuvarande mkdocs.yml, som istället har en manuellt kuraterad sektion. Följden: körs skriptet kan det lägga till en extra “Källkod:”‑sektion utöver den manuella.
scripts/generate_docs.sh: tunn wrapper som bara kör generate_docs.py.
scripts/create_comment_files.py
- Genererar kommentarmallar i docs/source_comments/<relativ/sökväg>.md för alla kodfiler (endast om fil saknas). Dessa filer uppdateras aldrig automatiskt av skriptet; avsedda för handskrivna kommentarer.
scripts/generate_comments_mapping.py
- Skapar en JSON‑mappning för kommentarer (comments-mapping.json) i både site/ och docs/. Frontend kan använda detta för att slå upp kommentarfilernas URL:er.
scripts/sync_docs_sources.py
- Säkerställer att vissa filer som refereras i docs finns speglade i docs/source/ (t.ex. .pre-commit-config.yaml, .env-example, scripts/generate_docs.py).

Layout‑override och frontend#

overrides/main.html
- Utökar Material‑temats baslayout och lägger till en högerspalt (<aside class="comments-panel">) där kommentarer för aktuell sida laddas.
docs/javascripts/extra.js
- På DOMContentLoaded initieras logik som:
  - Tvingar navigeringen att vara expanderad.
  - Hämtar rätt kommentarfil baserat på aktuell URL och laddar den från /source_comments/<stig>.md in i .comments-content.
docs/stylesheets/*.css
- Styling för paneler och layout (grid/flex, responsivt beteende, mm.).

Vad hamnar i `site/` efter build?#

site/source/**: HTML‑sidor som visar källfiler. Dessa härstammar från docs/source/**.md‑wrappers som i sin tur inkluderar riktiga filer via include-markdown.
site/source_comments/**: rena Markdown‑filer (inte renderade som HTML av MkDocs) kopierade av post‑build‑hooken. Dessa hämtas via fetch() av JS och renderas klient‑sida i kommentarpanelen.

Identifierade märkligheter och dupliceringar#

Dubbla hook‑vägar för samma sak

Både plugins.mkdocs-simple-hooks.on_post_build och hooks: använder scripts/mkdocs_hooks.py. Båda definierar/kallar on_post_build → sannolik dubbelkörning. Effekt: samma kopiering görs två gånger. Oskadligt men onödigt och förvirrande.

Dubbletter och felsorterade filer i docs/source/

Följande filer är 0 bytes i docs/source/: config.md, coordinates_manager.md, database.md, ml_train.md, models.md, weather_ingest.md. Dessa är troligen gamla placeholders som borde tas bort.
Det finns både docs/source/README.md (wrapper som inkluderar rotens README.md) och docs/source/README.md.md (kommentarmall). Kommentarmallar ska ligga i docs/source_comments/, inte i docs/source/.
Katalogen docs/source/docs/** innehåller många *.md.md som uppenbart är kommentarmallar för själva dokumentationsfilerna (t.ex. docs/source/docs/index.md.md). Även dessa hör hemma i docs/source_comments/**, inte under docs/source/**.
- Konsekvens: du får sidor i navigationen som visar “dokumentation om dokumentationen” (rå markdown som kod) samtidigt som samma innehåll redan visas som riktiga sidor. Detta upplevs som “dubbelgenererad markdown”.

Blandning av automatiskt genererad och manuellt kuraterad navigation

scripts/generate_docs.py kan skapa en fullständig “Källkod:”‑sektion i mkdocs.yml (dir‑first struktur). Samtidigt finns i dag en manuellt kuraterad meny “Source Code - ett par patchar efter:”. Om generatorn körs kan de samexistera → dubbleringar i sidomenyn.

Avvikande filterregler i generatorn

generate_docs.py exkluderar scripts/*, men den manuella menyn länkar ändå in filer under source/scripts/. Detta blir inkonsistent: vissa sidor uppdateras inte av generatorn utan måste underhållas manuellt.

Självreferens: docs inkluderas som “källa”

Historiskt har det skapats wrappers för filer i docs/ (syns under docs/source/docs/**). generate_docs.py undviker detta i dagsläget, men gamla filer ligger kvar.

Är detta den smartaste lösningen för demo/portfolio?#

Styrkor i nuvarande upplägg:

Tydlig separering mellan kod (visas som läsbar syntax) och kommentarer (manuellt skrivna, serveras separat och injiceras i UI).
Material‑tema + override ger en trevlig tvåspaltsvy som liknar “annoterad kodläsning”.
Automatgenerering via generate_docs.py kan återskapa sidor för hela repo snabbt.

Svagheter/komplexitet:

Dubbla vägar för hooks och mix av auto‑ vs manuellt kuraterad nav skapar lätt dubbletter och förvirring.
Felplacerade kommentarmallar i docs/source/** ger “dokumentation av dokumentation” och tomma sidor.
Inkludering av .md‑filer som “kodblock” kan vara rätt när avsikten är att visa råtext, men är ibland visuellt onödigt (t.ex. för README.md kan en renderad vy vara mer läsbar än en kodruta).

Sammanvägt: upplägget är bra för en teknisk demo, men behöver städning och några policy‑beslut för att eliminera dubbletter och göra navigationen konsekvent.

Rekommenderade åtgärder (ordning för låg risk → effekt)#

En väg för hooks

Välj EN metod: antingen plugins.mkdocs-simple-hooks ELLER hooks:. Rekommendation: behåll moderna hooks: (inbyggt i MkDocs ≥1.5) och ta bort mkdocs-simple-hooks från plugins.

Rensa felsatta filer i docs/source/

Ta bort alla *.md.md under docs/source/** (detta är kommentarmallar som ska ligga i docs/source_comments/**).
Ta bort 0‑bytes placeholders i docs/source/ (listade ovan).
Ta bort hela docs/source/docs/** då detta speglar dokumentationen som “källa”. Kommentarmotsvarigheten ska i stället ligga i docs/source_comments/docs/** om du vill kommentera dina egna docs.

Bestäm nav‑strategi (auto vs manuell)

Alternativ A – Manuell (rekommenderas för demo): Behåll dagens manuella “Source Code …”-sektion och stäng av den automatiska update_mkdocs_yml (kör inte den delen av generate_docs.py, eller lås filen med en kommentar).
Alternativ B – Automatisk: Låt generate_docs.py driva hela “Källkod:”‑sektionen och ta bort den manuella menyn. Kräver att exkluderingsreglerna i generatorn uppdateras så att den tar med allt du vill visa (inkl. scripts/ om önskat) och utesluter docs/ konsekvent.

Justera generatorns filterregler

Om du vill visa skript: ta bort "scripts/*" från exclude_patterns i generate_docs.py.
Säkerställ att docs/ alltid exkluderas från wrapper‑generering (det görs redan) och att gamla wrapper‑filer i docs/source/docs/** rensas.

.md‑filer: rendera vs “visa som kod”

Vid behov: ändra wrappern för .md så att de inkluderas utan kodblock när läsbar renderad markdown önskas. Ex:
- För .md: använd {! include-markdown "..." !} utan fence.
- För övriga filtyper: behåll kodblock med språk.

Valfritt: enkel “städ‑skript”

Lägg till ett litet Python‑/shell‑skript som:
- Tar bort docs/source/**/*.md.md.
- Tar bort 0‑bytes docs/source/*.md.
- Tar bort docs/source/docs/**.
- (Ev.) verifierar att alla kommentarmallar endast finns i docs/source_comments/**.

Verifiering efter städning#

Kör: ./scripts/generate_docs.sh (om du använder auto‑wrappers) och därefter mkdocs serve.
Kontrollera i sidomenyn att varje fil endast visas en gång och att “Källkod:”‑sektionen inte dubblettas med den manuella menyn.
Öppna en källsida (t.ex. source/src/app/utils.py.md) och bekräfta att kommentarpanelen laddar site/source_comments/src/app/utils.py.md korrekt.

Sammanfattning#

Dokumentationen byggs av en kombination av: wrapper‑sidor i docs/source/ (kodvy), kommentarmappar i docs/source_comments/ (manuella förklaringar), ett override‑tema (overrides/) samt en post‑build‑hook som publicerar kommentarerna i output.
Dagens “dubbelgenerering” kommer främst av blandning mellan auto‑/manuell navigation och felaktigt placerade kommentarmallar i docs/source/** (särskilt docs/source/docs/**) samt dubbla hook‑vägar.
Efter enkel städning + ett policybeslut kring navigation blir lösningen tydlig, lätt att underhålla och stark för ett portfolio‑case.