2025-08-30/31_sphinx_migration#

Datum: 2025‑08‑30 & 31 Författare: Carl & AI‑agent

Sammanfattning: Installerade Sphinx för första gången (appen där du läser detta) - det var för mycket motvind att göra vissa saker med Mkdocs så byte till Sphinx kändes befogat, och kul att testa något nytt - nu visas lekmannakommentarerna bra mycket bättre än tidigare. Se bild nedan för skillnaderna i Mkdocs avseende beskärd visning av högerpanelen - Mkdocs gillar inte att man pillar i det; Spinx är mer medgörligt, och kan passa syftet något bättre på sikt då det har litet fördelar vad gäller generera fram all dokumentation som nedladdningsbar pdf och så vidare.

Skärmklipp: Chrome vs Firefox#

Följande skärmklipp visar rendering i en Chrome‑baserad webbläsare (övre) och en Firefox‑baserad (nedre).

Chrome‑baserad rendering

Firefox‑baserad rendering

Sammanfattad kronologi (snabböversikt)#

  • 2025-08-30 → 2025-08-31: Initial migrering från MkDocs till Sphinx. Bytte tema, implementerade layout för kod+kommentarer och skapade grundläggande Sphinx extensions (inkl. custom code_comments).

  • 2025-08-31:

    • Dokumenterade tekniska val, mapping‑spec och problem i denna journal (detaljer nedan).

    • Snabba operationer för att stabilisera navigationen:

      • Removed generated nested index/index.rst som överskuggade vår master‑index.

      • Uppdaterade nav‑konverteringsskriptet så det inte genererar top‑level index.

      • Flyttade docs_sphinx/source/app → docs_sphinx/source/_app_backup för att eliminera dubbletter (app/ vs src/app/).

      • Regenererade nav‑stubbar och byggde HTML för att verifiera förändringar.

Senaste åtgärder (kort)#

  • Uppdaterade conf.py för att undvika att copy‑hook skriver över handkuraterade .rst-filer och för att exkludera temporära backup‑mappar från bygget.

  • Lagt till hjälpskript:

    • scripts/convert_mkdocs_nav_to_sphinx.py — genererar toctree‑stubbar från mkdocs.yml.

    • scripts/convert_mermaid_fences.py — konverterar fenced mermaid till Sphinx .. mermaid:: direktiv.

  • Skapade DOCS_MIGRATION_TODO.md i repo‑roten med prioriterad fixlista.

Se senare avsnitt för full teknisk detalj och loggutdrag.

Uppdatering: 2025-08-31 (AI-agent) — duplicates & nav conversion helper#

Kort sammanfattning:

  • Åtgärd: Flyttade två MD‑filer som orsakade Sphinx‑varningar (“multiple files found for the document”) till en backup‑mapp: docs_sphinx/source/_mkdocs_md_backup/.

  • Åtgärd: Uppdaterade docs_sphinx/source/conf.py så att copy‑hooken undviker att kopiera Markdown‑filer som skulle kollidera med existerande .rst-filer (därmed undviks framtida dubblettvarningar).

  • Åtgärd: Lagt till verktygsskript scripts/convert_mkdocs_nav_to_sphinx.py som läser mkdocs.yml och genererar gruppade index.rst-stubbar och en top‑level _mkdocs_generated_nav.rst. Skriptet är avsiktligt konservativt och skriver inte över befintliga filer utan --force.

  • Åtgärd: Raderade det tidigare synk‑skriptet scripts/sync_code_to_docs.sh och avvecklade automatisk kopiering av källkod till dokumentationsmappen; dokumentationen refererar nu direkt till src/app/ som enda källa (single source of truth).

Varför detta behövdes#

  • Bygget rapporterade varningar om att både index.rst och index.md fanns samtidigt (samma dokumentnamn). Sphinx kan tekniskt välja en av dem, men varningen är oönskad och leder till oklarhet om vilken källa som styr navigationen. Att flytta bort .md-kopiorna och hålla .rst som auktoritativt master‑dokument är ett säkrare tillstånd.

Hur verifiera

  1. Kör cd docs_sphinx && make html lokalt (se till att sphinx-build finns i din venv).

  2. Du bör inte se varningen “multiple files found for the document” för index eller infra/index längre.

  3. Kör konverteringsskriptet för att automatiskt generera nav‑stubbar:

    python3 scripts/convert_mkdocs_nav_to_sphinx.py --mkdocs mkdocs.yml --out docs_sphinx/source

    • Om du vill tvinga överskrivning av genererade filer: lägg till --force.

Nästa steg (rekommenderat)

  • Kör konverteringsskriptet och granska de genererade index.rst-stubbarna; börja konvertera de viktigaste innehållssidorna (Start/Intro, Källkod/Source overview, API) till reStructuredText där det görs enklast.

  • När de viktigaste sidorna finns som .rst kan vi stoppa kopieringshooken eller begränsa den till backup‑syften och sedan ta bort MkDocs‑konfigurationen.

Viktiga resultat i denna etapp (executive summary)#

  • Bytt tema till PyData Sphinx Theme med inbyggd light/dark‑toggle.

  • Implementerat tvåkolumnslayout: vänster kod, höger Comments – utan horisontell scroll och med radbrytning.

  • Comments laddas från statiska HTML‑fragment; robust felhantering med tydlig diagnos i UI.

  • Språkväxling (sv/en) med knappar som följer PyData‑stilen och fungerar i dark mode.

  • Högerspalt (secondary sidebar) avstängd globalt; comments tar hela högerkolumnen.

  • Fullbredds‑layout: PyData CSS overrides för .bd-page-width och .bd-article-container.

  • Smalare vänstersidebar, större text i både Comments och kod, större breadcrumbs.

  • Svenska rubriker i topp och meny: “Roadlake MLOps dokumentation”, “Kubernetes‑manifest”, “Skript”, “Slurm‑konfiguration”, “Slurm‑image”, “Tema‑överskrivningar”.

  • Egen theme‑toggle borttagen; varningar eliminerade. Pre‑commit grönt (black, isort, flake8, doc8, bandit, pip‑audit).

Tekniska ändringar (detaljer)#

Tema & konfiguration#

Kodexempel från conf.py:

html_theme = "pydata_sphinx_theme"
html_title = "Roadlake MLOps dokumentation"
html_theme_options = {
    # Place theme switcher in the navbar
    "navbar_end": ["theme-switcher", "navbar-icon-links"],
    # Remove the right-hand (secondary) sidebar completely
    "secondary_sidebar_items": [],
    # Optional: show prev/next buttons
    "show_prev_next": True,
}
html_static_path = ["_static"]
html_css_files = ["css/custom.css"]
html_js_files = ["js/comments_loader.js"]

  • html_theme = "pydata_sphinx_theme", html_title = "Roadlake MLOps dokumentation".

  • html_theme_options = {"navbar_end": ["theme-switcher","navbar-icon-links"], "secondary_sidebar_items": [], "show_prev_next": True}.

  • Svenska meny‑rubriker i k8s/index.rst, scripts/index.rst, slurm-config/index.rst, slurm-image/index.rst, overrides/index.rst.

Layout & stil#

  • Full width (CSS overrides) för sida och artikelcontainer.

/* Two-column code/comments layout */
.code-comments-container {
    display: flex;
    flex-wrap: wrap;
    width: 100%;
    border-top: 1px solid #e1e4e5;
}
.code-pane {
    flex: 1 1 50%;
    min-width: 400px;
    overflow-x: auto;
}
.comments-pane {
    flex: 1 1 50%;
    min-width: 400px;
    overflow-wrap: anywhere;
}

  • Vänster sidebar smalare; tvåkolumns‑comments (50/50); radbrytning i code/comments; större breadcrumbs.

  • Dark‑mode‑kontrast för icke‑aktiv språkknapp.

Comments‑pipeline#

  • comments_loader.js: hämtar /comments/{lang}/{path}.html, ersätter filändelse, visar full URL och instruktion för lokal HTTP‑server vid file:///.

  • conf.py kopierar comments vid build-finished till build/html/comments och loggar via sphinx.util.logging.

Direktivet code-with-comments#

Kodexempel från code_comments.py:

import os
from docutils.parsers.rst import Directive

class CodeWithComments(Directive):
    """Include source code with an AI comments pane alongside.

    Usage
    -----
    .. code-with-comments:: path/to/file.py [highlight_language]
        :comment-language: sv|en
    """
    required_arguments = 1
    optional_arguments = 1
    has_content = True
    option_spec = {
        "version": lambda x: x,
        "comment-language": lambda x: x,
    }

    def run(self):
        source_file = self.arguments[0]
        highlight_language = self.arguments[1] if len(self.arguments) > 1 else "text"
        comment_language = self.options.get("comment-language", "sv")

        env = self.state.document.settings.env
        rst_abs_path = env.doc2path(env.docname)
### 10. Framtida förbättrings-roadmap

- Utveckla integration för full multiversionshantering med automatisk grenvalidering.
- Implementera automatiserade pre-release-byggtester för HTML- och PDF-utdata.
- Utöka dokumentationspipeline med regelbunden säkerhetsskanning av genererat innehåll.
- Integrera kodexempelkontroll via lint-verktyg i CI.
- Lägg till visuell regressionstestning av UI-komponenter (kod/comments-layout).
        rst_abs_dir = os.path.dirname(rst_abs_path)
        abs_source_path = os.path.normpath(os.path.join(rst_abs_dir, source_file))
        normalized_source_path = os.path.relpath(abs_source_path, project_root).replace("\\", "/")

Kodexempel från code_comments.py#

.. code-block:: python :linenos: :emphasize-lines: 7-13

class CodeWithComments(Directive): required_arguments = 1 optional_arguments = 1 has_content = True option_spec = { “version”: lambda x: x, “comment-language”: lambda x: x, }

  • Path‑upplösning med env.doc2path(env.docname) + normalisering relativt projektroten.

  • Graceful fallback i HTML + build‑logg när fil saknas.

  • Rensat och formatterat enligt flake8/black.

Build, lint och säkerhet#

  • Alla hooks gröna. Imports flyttade och formattering fixad (E402/E302/BLK100/B007 m.fl.).

  • Lessons-learned och “Best Practices” görs synliga i navigation, särskilt med fokus på pipeline- och layoutvalidering.

7. API-dokumentation & kodintegration#

  • Plan för att flytta alla {::: app.module}/mkdocstrings-snuttar till motsvarande .. automodule::- och .. autoclass::-syntax.

  • Kurering av huvudsidor (Index, Source Overview, Arkitektur mm) för att lyfta alla varför och hur från kodbasen in i documentation-first-presentation.

8. Lessons learned från MkDocs-epoken – så undviker vi regressions#

  • En väg för hooks: Kopieringslogik (för kommentarer etc) löses alltid på ett ställe — ingen dubblettkörning.

  • Ingen legacy/vilda artefakter: Tomma kommentarer, .md.md-filer och gamla kod-wraps filtreras eller tas bort i automationsledet.

  • Manuellt kurerad navigation: Navstruktur byggs medvetet enligt arkitektur och portfolio-hierarki, inte fullauto.

  • Säkrare och robustare kodinjektion: All kodinjektion/kommentarinjektion sker via tydliga directives och dom-aware layout i stället för wildcard-JS i overrides.

  • Modern dokumentationspipeline: Docstring/hl_lines-highlight synkas automatiskt, med “lint” i pre-commit/build pipeline.

9. Plan - nästa steg#

  • Systematisk migrering av alla wrapper-sidor, API-refs och guides.

  • Successiv validering så samtliga högre krav på layout, kod+kommentar och navstruktur bibehålls och förbättras.

  • Portfolio-perfect presentation blir baseline med versionshantering av lessons-learned, driftproblem och designbeslut.

  • Fortlöpande dokumentation av varje steg i denna journalfil — uppdateras under hela migreringen.

Sammanfattning#

Vi lämnar en hackig, “Javascript-lagad” MkDocs-lösning bakom oss och bygger nu med Sphinx vidare på ett hållbart, rent, och portfölj-anpassat dokumentationssystem där exakt rätt placerad kod/kommentar-layout, nav och lessons-learned är första klassens invånare. All erfarenhet från utvecklingen i MkDocs — från pipeline-problem och artefakt-kaos till lessons-learned och stylingfixar — omvandlas till robusta arbetsmönster på Sphinx-sidan, med mål: noll regressions, maximal instruktionskraft och elegant presentation.

Uppdatering: 2025-08-31#

Kort sammanfattning:

  • Åtgärd: Fixed copy-hook i docs_sphinx/source/conf.py så att den inte längre skriver över existerande Sphinx-källor (inklusive index.md). Tidigare beteende gjorde att en kopierad index.md från MkDocs blev Sphinx master‑dokument och ersatte vår kontrollerade index.rst, vilket ledde till att toctree/navigation försvann i byggt HTML.

  • Effekt: Efter denna ändring kommer Sphinx att använda index.rst (det kontrollerade master‑dokumentet) och navigationen som specificeras där (toctree) återställs när du bygger om dokumentationen.

Åtgärder#

  • Uppdaterade conf.py copy-hook så att existerande filer alltid sparas (“skip existing files”).

  • Lade till/uppdaterade Sphinx index-/sektioner så att MkDocs-navigation kan mappas till Sphinx toctrees utan att vi skriver över handkurerade .rst-sidor.

Variera lokalt

  1. Se till att myst-parser är installerad i din virtuella miljö: pip install myst-parser.

  2. Bygg dokumentationen: cd docs_sphinx && make html eller sphinx-build -b html source _build/html.

  3. Kontrollera att navigeringen syns: öppna docs_sphinx/_build/html/index.html i en webbläsare (eller http://localhost:8008/index.html om du serverar _build/html).

Om navigationen fortfarande saknas

  • Kontrollera om docs_sphinx/source/index.md finns — om så är fallet och du inte vill använda Markdown-versionen, ta bort den (eftersom index.rst är avsett att vara master). Med nuvarande copy-hook ska index.md dock inte längre ersätta index.rst.

  • Kontrollera conf.py för master_doc (standard är index) och source_suffix så att .rst prioriteras eller att myst-parser är korrekt konfigurerad.

Föreslagen komplett migreringsplan (högnivå)

  1. Stabilisera basen

    • Säkerställ en stabil conf.py med följande kärn‑extensions: sphinx.ext.autodoc, sphinx.ext.napoleon, sphinx.ext.intersphinx, sphinx.ext.viewcode, sphinx.ext.todo, myst_parser (valfritt under övergång), sphinx-copybutton, sphinxcontrib-mermaid, och projektets egna code_comments.

    • Bestäm master‑dokument (index.rst) och se till att det innehåller en komplett toctree som speglar navigationen från mkdocs.yml.

  2. Automatisk nav‑konvertering

    • Skriv ett verktyg (scripts/convert_mkdocs_nav_to_sphinx.py) som läser mkdocs.yml och genererar toctree-stubbar i docs_sphinx/source (t.ex. generera index.rst samt per‑katalog index.rst med toctree).

  3. Inkrementell innehållsmigrering

    • Behåll Markdown via MyST till en början (så vi snabbt får feature‑parity).

    • Identifiera MkDocs-specifika Markdown‑features som pymdownx.snippets/superfences och ersätt dem med Sphinx‑ekvivalenter (t.ex. .. include:: för snippets).

    • För sidor som kräver mycket Sphinx‑funktionalitet (automodule, admonitions, mermaid), konvertera till reST där det förenklar underhållet.

  4. API / autogen

    • Ersätt mkdocstrings med Sphinx-autodoc/autosummary/autodoc‑generering. Skapa en api/-sektion med autosummary‑stubbar som genereras av sphinx-apidoc eller ett skript.

  5. Bygg‑pipeline och CI

    • Lägg till en GitHub Action/job som kör sphinx-build -b html samt sphinx-build -b linkcheck för att säkra att allt är länkat.

  6. Teman, overrides och assets

    • Migrera MkDocs overrides (CSS/JS) till Sphinx _static och _templates och validera att alla komponenter renderas identiskt.

  7. Decommission MkDocs

    • När vi har full parity (funktion, navigation, API‑sidor, automatisk generation och CI‑grindarna gröna), planera ett datum för att ta bort mkdocs.yml, MkDocs-specifika overrides och plugin‑konfiguration.

Nästa konkreta steg jag kan utföra nu (välj ett):

  • Köra en lokal Sphinx‑build här i miljön och verifiera att navigationen återkommer (jag behöver ditt ok för att köra bygget).

  • Implementera skriptet scripts/convert_mkdocs_nav_to_sphinx.py som genererar toctrees automatiskt.

  • Börja konvertera MkDocs‑specifika Markdown‑funktioner (snippets/superfences) till Sphinx‑inkluderingar.

Mappningar#

MkDocs to Sphinx/Read the Docs Mapping Specification#

Funktion / Arkitektur

MkDocs-metod/plugin / config

Sphinx/Read the Docs-lösning

Caveats / Anpassning

Theme & UI

material theme + custom CSS

sphinx_rtd_theme + custom CSS (html_css_files)

Läs in egna CSS/JS via html_static_path, themes mindre flexibla än Material

Code comments/AI panel

Egen JS (comments.js), CSS för panel; comment files i source_comments

Custom extension code_comments (_ext/code_comments.py), laddas via Sphinx extension

Måste säkerställa att panelen laddar data på rätt plats inom .rst-strukturen

Kopiera kodblock

content.code.copy feature (Material)

Ingen nativ, kan implementeras (JS, custom CSS) eller via sphinx-copybutton

Installera sphinx-copybutton och lägg till i extensions

Navigation

Manuell YAML i nav: i mkdocs.yml

Automatiskt via katalogstruktur och toctrees i .rst, ev. med toctree-direktiv

Underhåll av hierarki flyttas till .rst-filer och _toc.yml

Sökfunktion

search plugin

Inbyggt fulltext-sök i Read the Docs-temat (Elasticsearch-backend)

Mindre konfigurerbart än MkDocs, ingen extra plugin krävs

Auto-dokumentation (API)

mkdocstrings med paths, numpy-style och merges

sphinx.ext.autodoc, + sphinx.ext.napoleon för NumPy docstrings, lista paths i conf.py

Sphinx hanterar NumPy-stil via napoleon, ingen extra omskrivning krävs

Mermaid-diagram

Markdown direkt, (Material tolkar mermaid)

sphinxcontrib-mermaid-extension för mermaid-block

Installera sphinxcontrib-mermaid, markdown blir .. mermaid:: i .rst

Admonitions/info block

admonition extension i markdown

.. admonition:: och nativa .rst-direktiv

Syntax skiljer sig, ingen plugin krävs

Snippets/superfences

pymdownx.snippets, pymdownx.superfences

Sphinx har inbyggd support för code-blocks och kan importera .rst (no snippet plugin)

Ev. refaktorisera snippet-flöden till Sphinx includes eller inheritance

Extra Javascript

extra_javascript: [ comments.js ]

html_js_files i conf.py (t.ex. comments_loader.js)

Kontrollera att JS fungerar med Sphinx DOM-struktur och template

Auto-gen wrapper/docs

Script generate_documentation.py skapar markdown för kodfiler

Script genererar .rst-filer för import i Sphinx

Se till att alla .rst-filer följer toctree/hierarki-regler för Sphinx

Språkväxlare/multilang

Egna struktur eller JS, Material har plugin

Ingen nativ språkväxlare i Read the Docs, kan använda sphinx-intl eller Serve-translated docs

Kräver specialkonfig, ev. Docker-build för fler html ouput

Versionering dev_addr

dev_addr: 127.0.0.1:8005 i mkdocs.yml, versions noggrannhet/preview

Inbyggt i RTD, preview via RTD eller lokal make html

Ingen direkt motsvarighet för dev_addr, preview via lokal Sphinx build

Overrides/templates

custom_dir: overrides (Material)

_templates och custom Jinja2-teg i Sphinx, refereras via conf.py

Justera Jinja2 templates vid behov, Material overrides ej kompatibla

Noteringar#

  • All auto-dokumentation via docstrings, NumPy-format och Sphinx (med napoleon) är direkt kompatibelt; ingen manuell konvertering behövs.

  • Eventuell manuell överföring av nav-struktur sker genom toctree-direktiv eller i _toc.yml för HTML generering.

  • Anpassningar för comments/AI-panel sker genom att matcha DOM/callouts mellan Material och RTD-template, ev. uppdatering av custom JS/CSS.

Redo för merge för att implementera multiversion#

Beslut: Vi kommer avstå från multiversion-dokumentionsfunktioner just nu.

Description#

Introduces versioned documentation using sphinx-multiversion. This enables the documentation to be built and browsed for multiple codebase versions (branches/tags). This PR includes:

  • Adding sphinx-multiversion to dev-requirements.txt

  • Updating docs_sphinx/source/conf.py with appropriate multiversion config and whitelist regexes

  • Ensuring .. only:: html and .. smv:: current v1.0 present in index.rst

  • Preparation for GH tag (v1.0) for full multi-version experience

Instructions#

After merging:

  1. From main, create and push a Git tag:

    git tag v1.0
git push origin v1.0

  2. Run the following to build versioned docs:

    sphinx-multiversion docs_sphinx/source docs_sphinx/_build

  3. Verify that multiple version dropdown appears in HTML output.

Beslut: avstår från sphinx-multiversion för nu (tillfälligt)#

Efter närmare utredning har vi beslutat att inte fortsätta implementera sphinx-multiversion i nuläget. Sammanfattning av skälen:

  • Kompatibilitet: sphinx-multiversion i dess nuvarande form är inte kompatibel med Sphinx efter version 5 (vi kör nyare Sphinx i vår pipeline), vilket skulle kräva antingen att vi kör en äldre Sphinx eller att vi underhåller en egen fork av extensionen — båda alternativen innebär en hög kostnad i underhåll för en funktion som för oss är “nice-to-have”.

  • Behovsbedömning: Vi förväntar oss mycket sällan behov av att publicera parallella dokumentationsversioner för detta projekt; det är acceptabelt att i de få fall då det behövs bygga separata dokumentationsutgåvor.

Vi lämnar idén som en framtida möjlighet (en template för senare bruk), men prioriterar nu att stabilisera Sphinx‑basen och nå feature parity mot vad vi hade i MkDocs för auto‑genererad API‑dokumentation.

Autogenerad dokumentationsfunktion för att ta över efter mkdocstrings och griffe#

För att få samma (eller bättre) autogenererade API‑sidor som vi tidigare skapade med mkdocstrings + griffe behöver vi främst säkerställa att Sphinx kan:

  • läsa våra utförliga NumPy‑docstrings (done via sphinx.ext.napoleon),

  • generera modul‑/klass‑sidor automatiskt (via sphinx-apidoc eller autosummary/autodoc), och

  • presentera typannoteringar och init‑dokstringar på ett likvärdigt sätt.

Konkreta steg och config‑snippet (lägg i docs_sphinx/source/conf.py):

# Extensions
extensions += [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.autosummary',
    'sphinx.ext.viewcode',
    'sphinx.ext.intersphinx',
    'sphinx_copybutton',
    'sphinx_autodoc_typehints',
]

# Autodoc behaviour
autoclass_content = 'both'  # include class docstring and __init__
autodoc_default_options = {
    'members': True,
    'undoc-members': False,
    'show-inheritance': True,
}
autosummary_generate = True
autodoc_typehints = 'description'

Exempel‑workflow för att generera API‑sidor:

  1. Kör sphinx-apidoc för att skapa stubbar:

sphinx-apidoc -f -o docs_sphinx/source/api src/app

  1. Bygg dokumentationen och kontrollera api/‑sektionen:

cd docs_sphinx && sphinx-build -b html source _build/html

Ytterligare förbättringar:

  • sphinx_autodoc_typehints eller autodoc_typehints förbättrar hantering av annoteringar (motsvarar mkdocstrings show_signature_annotations).

  • autoclass_content = 'both' efterliknar mkdocstrings merge_init_into_class.

  • viewcode ger länkar till källan (motsvarar mkdocstrings show_source).

“Source file not found” och nya robusthetskrav#

Bakgrund till regressionen#

Efter “grön” migrering, visade det sig att vissa .rst-sidor med custom .. code-with-comments::-direktivet aldrig laddade själva källkoden – trots att både navigation, toctrees och övriga sidor fungerade. Problemet blev akut när gamla “Source file not found”-fel återuppstod i Sphinx–trots att rätt källa låg på disk där den borde.

Felsökningsåtgärder och metodik#

  • Genomförde systematisk test av paths: test av absoluta, relativa och kombinatoriska (../../.., osv) sökvägar i .rst-filer mot verklig filstruktur

  • Lade in diagnostic-printar/loggar i code_comments.py: logg-strängar till Sphinx build-log och synliga “Failed to fetch source…”-injekt i HTML om fil ej fanns

  • Säkerställde att källfiler verkligen existerade (via ls -l från build-root)

  • Provade olika riktningar på referenser: relativt till docs_sphinx/source, från projektroten, och via symlinks

  • Rensade alla legacy .rst och templates med för långa underline-tecken och otillåtna directiv

  • Tog bort alla Sphinx-konfigrations-warnings (t.ex. display_version i conf.py)

  • Provade funktionsminimal .rst som bara inkluderar en exempelfil för isolerad test

Vad upptäcktes?#

1. Sphinx’ path-resolution är CWD-beroende, ej robust vs. MkDocs

  • Paths i standard-Sphinx-directiv hanteras RELATIVT till build-direktivet, men custom-directives måste själva räkna ut detta.

  • Små fel i directory-djup leder till att source-filer “inte finns” trots korrekt filstruktur.

  • Round-trip via scripts/generate_documentation.py kan ha output som ibland tappar rätt “../../”-djup.

2. Vår custom directive och fallback-medveten UX

  • Funktionaliteten förbättrades med fallback: när fil saknas visas HTML-warn, men bygget kraschar aldrig.

  • Felet hissas även i “build log”-nivå, vilket tillfredsställer devops och CI.

3. Robusthets lesson learned

  • Kritiskt i all framtida dokumentationspipeline: all code injection och file fetch ska göras fail-visibly och tyst för både bygget (log) och output (HTML).

  • Jämfört med MkDocs-material—där wildcard-inklusion ofta slukade error—så explicit fallbacks i Sphinx ger portföljfördel i robusthet och predictability.

Vad återstår?#

  • Fixa vissa “See also” avsnitt för API-dokumentationen.

  • Fixa flicker vid öppnande av ny källkodsfil från Src vyn.

  • Snygga till bildvisning.

  • Kör om LLM-kommentarerna för att bryta ut mermaid diagram och göra för varje program, och hålla dem separata för det nu inkonsekventa medtagandet i lekmannakommentarrna.

Erfarenheter och best practices från denna regression#

  1. Explicit path-debuggi, undvik implicit CWD: All dokumentationskod (custom directives, scripts) ska alltid logga exakta path som testas mot disk – annars förlorar man snabbt kontrollen vid pipeline-ändringar.

  2. Fail visibly > fail silently: Alla pipeline-lager (Sphinx, .rst, extensions, build-skript) MÅSTE rendera fel synligt, inte bara logga djupt i bygget.

  3. Regressionstestar ALLA paths vid varje build: Alla generationer av .rst eller dynamic includes ska testas i CI mot verklig diskstruktur, och test-strängar ska granskas inför PR-merge.

  4. CI-validering av genererade .rst-filer: Ett dedikerat CI-jobb kör sphinx-build --warning-is-error på alla genererade .rst-filer för att säkerställa att inga varningar eller fel uppstår, samt verifierar att katalogstruktur och innehåll följer definierade riktlinjer.

  5. Temawarnings och titles: Sphinx är striktare än MkDocs; ornda genast eventuella lint-warnings kopplat till theme och syntax.