Sphinx-Metrics
Umsetzung: eher nicht
Kennzahlen aus Google Analytics, Grafana und Co. direkt in der Dokumentation.
Problem
Wie oft eine Seite gelesen wird oder wie sich ein Projekt entwickelt, steht in Tools wie Google Analytics oder Grafana. Wer die Doku liest, sieht davon nichts – und wer die Zahlen sucht, muss erst Zugang zu diesen Tools bekommen.
Lösung
Eine Sphinx-Erweiterung holt Kennzahlen aus externen Quellen und zeigt sie direkt in der Dokumentation an, zum Beispiel Seitenaufrufe pro Kapitel oder Build-Zeiten. Neue Quellen kommen über austauschbare „Treiber“ dazu.
Tech
Python, Sphinx-Erweiterung mit eigenen Directives; Treiber für die APIs von Google Analytics, Grafana und Co.; Abruf beim Build mit Cache.
Smart Code Block
Umsetzung: wahrscheinlich
Code und sein Ergebnis aus einer einzigen Quelle zeigen.
Problem
Wer Dokumentation über rst oder Markdown schreibt, zeigt oft den Code und das Ergebnis daneben. Dafür steht derselbe Code zweimal in der Datei: einmal als Code-Block, einmal zum Ausführen. Ändert man nur eine Stelle, passen beide nicht mehr zusammen.
Lösung
Ein „smarter“ Code-Block, der aus einer Quelle beides erzeugt: den Code und das gerenderte Ergebnis – zum Beispiel in zwei Tabs „Ergebnis“ und „Code“.
Tech
Python, Sphinx-Directive, die ihren Inhalt parst und zusätzlich als Code-Block ausgibt; Tabs über sphinx-design.
Sphinx-Autosar
Umsetzung: eher nicht
AUTOSAR-Architekturen aus ARXML-Dateien dokumentieren und mit Anforderungen verlinken.
Problem
In Automotive-Projekten steckt die Softwarearchitektur in ARXML-Dateien von AUTOSAR. Anforderungen, Spezifikationen und Tests liegen woanders. Eine Verbindung zwischen beiden gibt es meist nur von Hand.
Lösung
Eine Sphinx-Erweiterung liest ARXML-Dateien und erzeugt daraus eine Architektur-Dokumentation, ähnlich einer API-Doku. Software-Komponenten, Runnables und Co. werden zu Sphinx-Needs-Objekten, die sich mit Anforderungen und Tests verlinken lassen.
Tech
Python, ARXML-Parser, Sphinx-Needs für Objekte und Traceability.
