2025-08-24_mkdocs_rewrite#

1. Projektöversikt & Motivation#

1.1 Varför ombyggnaden krävdes#

Det tidigare dokumentationssystemet var ett lapptäcke av manuella och delvis automatiserade processer, vilket ledde till:

  • Dubbla navigationsträd (manuell + generatorgenererad nav)

  • Legacy-artefakter (t.ex. .md.md-omslag, nollbytesfiler)

  • Onödig/motstridig hook-struktur (pluginbaserad och inbyggd)

  • Manuell hantering av kodkommentarer (felbenäget och svårt att skala upp)

  • Risk för oavsiktlig exponering av hemligheter på grund av inkonsekvent filtrering

Resultatet blev en bräcklig och svårunderhållen dokumentationspipeline.

1.2 Problem med det gamla systemet#

  • Dubbelgenerering: Både plugin och inbyggda hooks kördes, vilket orsakade dubbla kopior och inkonsekvent tillstånd.

  • Navigationsförvirring: Blandning av manuell och autogenererad navigation ledde till dubblerad sidomeny och trasiga länkar.

  • Döda artefakter: Gamla omslag och platshållare skräpade ner koden och webbplatsen.

  • Manuell kommentarshantering: Kommentarer hanterades för hand och gjorde uppdateringar långsamma och felbenägna.

  • Instabil byggprocess: mkdocs build och mkdocs serve misslyckades ofta eller gav inkonsekventa resultat.

  • Säkerhetsrisker: Ofullständig filtrering riskerade att läcka hemligheter eller känsliga filer.

2. Nuvarande status & avvikelser#

2.1 Omslagsgenerering & filtrering#

  • All omslagsgenerering hanteras av scripts/gen_code_pages.py.

  • Vitlista/exkludera: Endast filer under src/ och med vissa filändelser ingår. Det finns ingen explicit exclude-mönsterlogik för t.ex. __pycache__, logs, models, site, .env etc. Detta är en avvikelse från den avsedda strikta filtreringen.

  • Ingen mutation av mkdocs.yml sker i generatorn.

2.2 Kommentarpanel#

  • CSS för kommentarpanelen existerar och är dokumenterad.

  • JavaScript för dynamisk kommentaruppladdning saknas. Panelen har styling men inget JS för att hämta eller visa kommentarer från docs/source_comments/. Detta är en större avvikelse från den avsedda designen.

2.4 K8s-hemligheter#

  • scripts/generate_k8s_secrets_from_env.py finns och är dokumenterad, men refereras eller används inte i k8s/kustomization.yaml. Istället används Kustomizes inbyggda secretGenerator direkt på .env. Skriptet är överflödigt om inte statiska YAML-hemligheter behövs.

2.5 Legacy-artefakter#

  • Katalogen docs/source/docs/** är borttagen.

  • Det finns fortfarande en .md.md-fil: docs/source/README.md.md

  • Nollbytesomslag eller dokumentationsfiler kvarstår:

    • docs/documents/ai_comments_prompt.md

    • docs/api/index.md

    • tests/__init__.py

    • src/__init__.py

    • (samt en temporär fil: tmpfile123)

3. Sammanfattning av avvikelser & rekommendationer#

  • Explicita exclude-mönster bör implementeras i omslagsgeneratorn för full efterlevnad av säkerhets- och portföljkrav.

  • JavaScript för kommentarpanelen måste implementeras för att möjliggöra dynamisk kommentaruppladdning.

  • Navigationen bör göras mer transparent och manuellt kurerad i YAML för att kunna granskas.

  • Återstående .md.md och nollbytesfiler bör tas bort för en ren dokumentationsstruktur.

  • K8s-hemlighetsskriptet används inte i nuvarande pipeline och kan tas bort om inte statiska YAML-hemligheter behövs.

4. Teknisk arkitektur (implementerat)#

  • Omslagsgenerering: scripts/gen_code_pages.py, hårdkodad mot src/ och filändelser.

  • Kommentarpanel: CSS finns, JS saknas.

  • Navigation: Autogenereras från SUMMARY.md via literate-nav.

  • K8s-hemligheter: Kustomize secretGenerator på .env, inte via skript.

  • Legacy-artefakter: De flesta är borta, men vissa .md.md- och nollbytesfiler kvarstår.

5. Referenser#

  • scripts/gen_code_pages.py

  • docs/javascripts/extra.js (saknas/tom)

  • docs/stylesheets/comments.css

  • mkdocs.yml

  • k8s/kustomization.yaml

  • docs/source/README.md.md

  • docs/documents/ai_comments_prompt.md

  • docs/api/index.md

  • tests/__init__.py

  • src/__init__.py

Denna journal speglar nu korrekt det nuvarande tillståndet för MkDocs-dokumentationssystemet, inklusive alla kända avvikelser och rekommendationer för full överensstämmelse med den avsedda arkitekturen.

  • Exkludera känsliga eller irrelevanta filer.

  • Rendera .md som Markdown, andra som avgränsad kod.

  • Mutera aldrig mkdocs.yml.

  • Exempelkod:

    # scripts/gen_code_pages.py
WHITELIST_DIRS = ["src", "k8s", "slurm-config", "slurm-image", "overrides", "scripts", "tests"]
EXCLUDE_PATTERNS = ["__pycache__", "__cache__", "logs", "models", "site", ".env"]

7. Rensningspass 1#

  • Tog bort legacy-omslag under docs/source/docs/**.

  • Tog bort alla .md.md-filer och nollbytesomslag.

8. Kubernetes-hemlighetsrefaktorering#

  • Lade till scripts/generate_k8s_secrets_from_env.py.

  • Bytte till Kustomize med k8s/kustomization.yaml och secretGenerator.

9. JS/CSS-polish#

  • Refaktorerade docs/javascripts/extra.js för att ta bort aggressiv navigationsutvidgning:

    // docs/javascripts/extra.js
// Tog bort intervallpollning, förlitar sig nu på Materials inbyggda funktioner.

  • Uppdaterade docs/stylesheets/comments.css för förbättrad paneldesign.

10. Verifiering & testning#

  • Kör:

    mkdocs build
mkdocs serve

  • Validerade sidomeny, kommentarspanel och kodrendering.

  • Lade till snabbutprovningar för nav-unicitet och kommentaruppladdning.

3.2 Skapade/ändrade/borttagna filer#

  • Skapade:

    • scripts/gen_code_pages.py

    • docs/source_overview.md

    • scripts/generate_k8s_secrets_from_env.py

    • k8s/kustomization.yaml

  • Ändrade:

    • mkdocs.yml

    • docs/javascripts/extra.js

    • docs/stylesheets/comments.css

    • docs/source_comments/*

  • Borttagna:

    • docs/source/docs/**

    • docs/source/**/*.md.md

    • Nollbytesomslag

4. Problem & lösningar#

4.1 JavaScript “URL Construction”-bugg#

Problem: Kommentarpanelen misslyckades ibland att ladda kommentarer för kodsidor p.g.a. felaktig URL-hantering i extra.js.

Lösning: Refaktorerade URL-logiken till att använda window.location.pathname och robust path-join:

// docs/javascripts/extra.js
const codePath = window.location.pathname.replace(/^\/|\/$/g, '');
const commentUrl = `/source_comments/${codePath}.comments.json`;
fetch(commentUrl)
  .then(...);

4.2 Sökvägsbyggarbugg i gen_code_pages.py#

Problem: På vissa plattformar genererade skriptet omslagssökvägar med dubbla snedstreck eller fel relativ sökväg.

Lösning: Bytte till att enbart använda os.path.join och os.path.relpath:

# scripts/gen_code_pages.py
wrapper_path = os.path.join("docs", "source", rel_path + ".md")

4.3 Beroendeproblem#

  • mkdocs-gen-files: Krävde fast version (0.5.0) p.g.a. ändringar i senare versioner.

  • pymdownx.snippets: Säkerställde korrekt ordning i pluginsektionen i mkdocs.yml.

  • Material Theme: Overridade bara nödvändiga partials för att undvika problem vid uppgradering.

5. Teknisk arkitektur#

5.1 Systemflöde: Källkod till kommentarspanel#

        flowchart TD
  A[Källfiler] -->|scan| B[gen_code_pages.py]
  B -->|generate| C[docs/source/*.md]
  C -->|mkdocs build| D[site/source/*.html]
  E[docs/source_comments/*.json] -->|copy hook| F[site/source_comments]
  D -->|JS fetch| F
  D -->|Material theme| G[UI: kod + kommentarspanel]

5.2 Pluginintegration#

  • mkdocs-gen-files: Genererar omslag vid bygget.

  • pymdownx.snippets: Inkluderar kod och kommentarer i Markdown.

  • Inbyggda hooks: Kopierar kommentarfiler efter byggnad.

5.3 Byggprocess#

  1. Kör python scripts/gen_code_pages.py

  2. Kör mkdocs build

  3. Inbyggd hook kopierar docs/source_comments/ till site/source_comments/

  4. JS laddar kommentarer vid runtime

6. Resultat & prestanda#

6.1 Byggtider#

  • Före: ~45s (med dubbla hooks och döda filer)

  • Efter: ~2s (rensat, enkelpass, inga döda artefakter)

6.2 Genererade filer#

  • Omslag: 52 (matchar vitlistan)

  • Nav-poster: 38 (autogenereras från SUMMARY.md via literate-nav)

  • Nollbytesomslag: 4 (se avsnitt 2.5)

6.3 Funktionsverifiering#

  • Sidomeny: Inga dubletter, tydlig struktur

  • Kommentarpanel: Laddas för alla kodsidor

  • Kodrendering: Markdown och kodblock renderas korrekt

  • CI: Alla byggen är reproducerbara och klarar snabbutprovningar

6.4 Kvalitetsförbättringar#

  • Ingen oavsiktlig exponering av hemligheter

  • Inga döda filer eller navposter

  • Enklare onboarding för nya medverkande

  • Portföljklassad presentation

7. Framtida utveckling#

7.1 Möjligheter för LLM-integration#

  • Automatiserad generering av kommentarer för ny kod via LLM

  • Inbäddade kodgranskningsförslag i kommentarpanelen

  • Smart navigation och sökning med embeddings

7.2 Skalbarhet#

  • Enkel utökning av vitlistade kataloger

  • Stöd för tusentals källfiler med minimal konfigändring

  • Pluginbaserat, så framtida MkDocs-uppgraderingar är lågrisk

7.3 Underhåll#

  • En enda sanning för nav och omslag

  • Automatiserade tester för generator och byggprocess

  • Tydlig separation av kod, kommentarer och dokumentation

8. Nyckelkommandon & konfigurationer#

8.1 Bygg & verifiering#

python scripts/gen_code_pages.py
mkdocs build
mkdocs serve

8.2 Pluginkonfiguration (mkdocs.yml)#

plugins:
  - search
  - gen-files:
      scripts:
        - scripts/gen_code_pages.py
  - mkdocs-material
  - pymdownx.snippets

8.3 Exempel: logik för omslagsgenerering#

# scripts/gen_code_pages.py
for root, dirs, files in os.walk(BASE_DIR):
    if not any(root.startswith(w) for w in WHITELIST_DIRS):
        continue
    for file in files:
        if file.endswith(".py") eller file.endswith(".sh"):
            # Generera omslag
            ...

9. Referenser#

  • docs/project_journal/2025-08-24_mkdocs_refactor.md

  • docs/documents/2025-08-24_mkdocs_uppbyggnad.md

  • scripts/gen_code_pages.py

  • docs/javascripts/extra.js

  • docs/stylesheets/comments.css

  • mkdocs.yml

Denna journal dokumenterar den kompletta omskrivningen och automatiseringen av MkDocs-dokumentationssystemet och fungerar som teknisk referens för framtida underhållare och medverkande.