2025-08-25_mkdocs_ai_genererade_enkla_sammanfattningar#

Den här journalen dokumenterar det fullständiga arbetet för att göra källkodsidor njutbara:

  • tillförlitlig syntaxmarkering och inbäddade kodsnuttar

  • kuraterad navigation och automatiskt genererat API-index

  • en högersidbar Kommentarpanel driven av LLM-innehåll (med språkomkopplare)

  • ren pre-commit-integration, stabila lokala byggen och skydd mot regressioner

Målsättningar#

  • Fixa trasig markering och snutthämtning för kodomslag

  • Bibehåll kuraterad navigation samtidigt som ett auto-genererat API-index skapas

  • Lägg till en kommentar-sidopanel på “Källkod”-sidor med SV/EN-innehåll

  • Gör gränssnittet lättläst: markerade docstrings, bredare kommentarpanel, radbrytning för kod

  • Säkerställ att pre-commit-hooks fungerar tillförlitligt på varje maskin och i CI

Viktiga förändringar (Översikt)#

  • Pre-commit-stabilitet och YAML-korrigeringar (tillåt multi-dokument YAML, ignorera backup-filer)

  • Sync-/bygd-hooks som fungerar oavsett venv-aktivering

  • Omslagsgenerering fixad till att använda projektrrotsrelativa sökvägar och robusta kodblock

  • mkdocstrings-baserad API-dokumentation, auto-genererad och grupperad

  • Högersidig kommentarpanel (SV/EN) som laddar HTML-fragment per fil

  • CSS/JS som breddar sidopanelen endast när kommentarer finns och radbryter långa kodrader

Pre-commit och verktyg#

  • .pre-commit-config.yaml

    • check-yaml: --allow-multiple-documents och exkluderar backup_mkdocs_*/site/

    • sync-mkdocs-code och mkdocs-build: pass_filenames: false

    • mkdocs-build: aktiverar .venv automatiskt om den finns

    • Bytte Black till officiella psf/black-repo (formaterar endast Python-filer)

  • Skript är körbara och anropas rent av pre-commit

Snippets & Markering#

  • scripts/generate_documentation.py

    • Använder pymdownx.snippets med base_path: . (rot-relativa inkluder)

    • Markerar Python-docstrings automatiskt med hl_lines

    • Omslagslayouten innehåller nu:

      • front matter code_rel_path

      • H1 ”Fil: …”, och H2 ”Källkod” för att säkerställa att ToC renderar

      • inhägnad kodblock med --8<-- include

  • mkdocs.yml

    • markdown_extensions: pymdownx.snippets, pymdownx.highlight, pymdownx.superfences

API-dokumentation (Auto, grupperad)#

  • scripts/mkdocs_api_docs_hook.py

    • Använder mkdocs-gen-files för att skapa en sida per app.<modul> under api/app/

    • Auto-index: api/app/index.md med kort modulbeskrivning (första docstring-raden)

    • Navigationsinjektion (via hooks): lägger till ett topplänks “Kodstruktur”-objekt

    • Indelat i: Kärna, Applikation, Koordinater & Träning, och Övrigt

  • mkdocs.yml

    • plugins: gen-files med vårt script samt mkdocstrings (numpy-stil)

    • hooks: både prebuild-sync och API-docs-hook

Kommentar-sidopanel (SV/EN)#

  • overrides/partials/toc.html

    • Renderar kommentarsblocket endast på sidor som tillhandahåller page.meta.code_rel_path

    • Innehåller ett litet verktygsfält med SV- och EN-knappar

    • JavaScriptet har flyttats till en global fil för att undvika dubbel SPA-prenumeration

  • docs/javascripts/comments.js

    • Enda globala prenumeranten till document$

    • Lägger till/tar bort has-comments-pane-klass på body beroende på om panelen finns

    • Laddar HTML från /assets/comments/code/<lang>/<code_rel_path>.html

    • Tar bort dubbla laddningar med ett minnescache

  • docs/stylesheets/comments_layout.css

    • Breddar högersidopanelen när panelen finns (≈ dubbla bredden)

    • Radbryter långa kodrader på sidor med kommentarer

LLM-innehållspipeline (säker, tvåstegs)#

  • scripts/generate_comments_with_llm/send_cli.py

    • Skickar prompts till OpenAI-kompatibla eller Azure OpenAI (läser från .env)

    • Sparar Markdown-resultat till scripts/generate_comments_with_llm/out/{sv|en}/<code_rel_path>.md

    • Upptäcker målfiler från omslags front matter, kodinclusions eller src/app/*.py

  • scripts/generate_comments_with_llm/render_and_stage_comments.py

    • Konverterar Markdown → HTML och skriver till docs/assets/comments/code/{sv|en}/<code_rel_path>.html

    • Tar bort yttre kodblock om hela svaret är inhägnat

    • Möjliggör inhägnad kod och kodmarkering i renderad HTML

  • scripts/generate_comments_with_llm/repomix_cli.py

    • Valfri hjälpare för att förbereda prompts/platshållare

  • scripts/generate_comments_with_llm/README.md

    • Komplett användarguide och exempel

Stylingförbättringar#

  • docs/stylesheets/highlight-docstrings.css

    • Mycket ljusblå bakgrund för Python-docstrings i kodblock

  • docs/stylesheets/comments_layout.css

    • Breddare kommentarpanel och kodradbrytning endast när kommentarer finns

Felsökningsnoteringar#

  • Om kommentarpanelen inte visas, kontrollera att sidan har code_rel_path front matter

  • Om kod visas med råa inhägnader i kommentarpanelen, kör om staging för att tillämpa fence-stripping

  • SPA-navigation: vi använder en enda global prenumerant; undvik att lägga till sidlokala skript som ombinder vid varje vy

  • ToC kräver H2/H3-rubriker. Omslaget innehåller ”## Källkod” för att säkerställa att sidopanelen syns

Uppföljningar / Idéer#

  • Valfritt: dölj ”## Källkod” från synliga ToC med CSS men behåll sidopanelen

  • Lägg till Makefile-targets för send-all, stage-all-sv, stage-all-en

  • Lägg till indikator på språkomkopplaren (markerad knapp)

  • Dämpa deprecated-varningar från mkdocs-autorefs i serve-läge vid behov

Sammanfattning#

Nu har vi:

  • Stabil, kuraterad navigation och ett grupperat, auto-genererat API-index (“Kodstruktur”)

  • Robusta källkodsomslag med tillförlitliga kodsnuttar och docstring-markering

  • En språkmedveten kommentars-sidopanel som laddar för-renderad HTML per fil

  • En säker, tvåstegs LLM-innehållspipeline som håller docs/ rent fram till staging

  • Pre-commit-hooks som bygger dokumentation och kodlindning pålitligt i alla miljöer

Detta gör dokumentationen både portföljklassig och praktiskt användbar, med balans mellan automation, tydlighet och säkerhet.