Quellcode-Dokumentation mit DocFX und Mermaid.js

Zu Zeiten von Markdown und gezielter Quellcode Dokumentation wird es immer wichtiger auch Bilder in seinen Beschreibungen zu hinterlegen. Ablauf-, Zustands oder Fluss-Diagramme können sehr hilfreich bei der Erklärung vorhandener Strukturen oder getroffene Entscheidungen sein. Leider sind Strukturen und Entscheidungen in unserer agilen Welt sehr flüchtig und unterliegen einer stetigen Änderung.

Jeder Entwickler kennt wahrscheinlich das schlechte Gefühl eine Grafik für seine aufwendig entworfene Dokumentation in irgeneinem Grafik-Programm zu entwerfen und diese dann als Binär- oder XML-, bzw JSON-Datei im Quellcode Repository einzuchecken. Eine Änderungshistorie ist dann eigentlich nur noch über den Kommentar des Commits gegeben. Alle Team-Mitglieder müssen dann ebenfalls das Grafik-Programm, möglichst in der gleichen Version, installiert haben und in dem verwendeten Grafik-Programm geschult sein.

Eine mögliche Lösung ist der Einsatz von DocFX und Mermaid.js. Dabei dienst DocFX als Quellcode-Dokumentations-Generator und Mermaid.js als Dialekt zum Beschreiben von Diagrammen und Charts.

Bei der Erstellung dieses Posts liegt DocFX in Version 2.52 und Mermaid.js in Version 8.5.0 vor.

Um Mermaid in DocFX einzubinden müssen einige Templates von DocFX überschrieben werden. Dazu bietet es sich an einen eigenen DocFX-Ordner im Quellcode-Repository anzulegen, in denen man Artikel, Konfigurations-Dateien oder die erwähnten Template-Informationen ablegt. Meistens wählt man zu Begin der Dokumentation ein Template, mit welchem man die statisch erzeugten Dateien designed. Ein Wechsel des Templates zu einem späteren Zeitpunkt bedeutet einen nicht zu unterschätzenden Aufwand bei der Migration.

DocFX-Konfiguration

Da in der hier verwendeten DocFX-Version zwei Markdown-Prozessoren verbaut sind, sollte man die Konfiguration so anpassen, dass der Website-Generator DocFX den zukunftssicheren Prozessor Markdig verwendet.

"markdownEngineName": "markdig"

Template-Struktur

Im DocFX-Ordner erzeugt man dann eine Order-Struktur für das Einbinden von Mermaid.

- docfx
  - template
    - partials
    - styles

Um Template-Dateien zu überschreiben muss die Konfiguration von DocFX in der docfx.json-Datei des Projektes angepasst werden.

"template": [
  "default",
  "docfx/template"
]

Somit werden die Dateien, des default Templates und des docfx/template-Ordners zusammengeführt, bzw. überschrieben.

On-Premises Hosting von Mermaid.js in Projekt-Dokumentation

Die Javascript-Dateien von Mermaid läd man von UNPKG in den styles-Ordner und benennt die Datei info.html in mermaid.html um, damit man die Versions-Information zu einem späteren Zeitpunkt nachvollziehen kann.

Template anpassen

Nun muss die Datei angepasst werden, welche die Javascripte im Template einbindet. Dafür muss die entsprechende Datei im partials-Ordner abgelegt und angepasst werden. In diesem Beispiel verwenden wir die Datei scripts.tmpl.partial aus dem default-Template und laden uns diese aus dem GitHub-Repository herunter und passen Sie entsprechend an.

<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
<script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript" src="{{_rel}}styles/main.js"></script>

<!-- mermaid support -->
<script type="text/javascript" src="{{_rel}}styles/mermaid.min.js"></script>
<script>
    mermaid.initialize({
        startOnLoad: false
    });

    window.onload = function () {
        const elements = document.getElementsByClassName("lang-mermaid");
        let index = 0;

        while (elements.length != 0) {
            let element = elements[0];
            mermaid.render('graph'+index, element.innerText, (svgGraph) => {                    
                element.parentElement.outerHTML = "<div class='mermaid'>" + svgGraph + "</div>";
            });
            ++index;
        }
    }
</script>

Fazit

Das Einbinden von Mermaid.js in DocFX in ein bestehendes DocFX-Projekt beträgt circa 15 Minuten, falls keine Besonderheiten in der Template-Struktur vorhanden sind. Der Nutzen ist sehr hoch, aber die anderen Entwickler müssen die Sytax von Mermaid lernen.

Erstellt in DotNet am 25.04.2020