Dokumentation
Für die Funktionsdokumentation wird hauptsächlich das Matlab Simulink Modell verwendet. Hierfür werden ausgewählte Abbildungen von den verschiedenen Funktionsebenen erstellt und mit erklärendem Kommentar in die Dokumentation eingefügt. Eine Gruppierung von einzelnen oder mehreren Abbildungen in Kapiteln ist ebenfalls möglich. Diese strukturierte Aneinanderreihung von Abbildungen mit Erklärung stellt einen zentralen Bestandteil der Funktionsdokumentation dar.
Die Generierung der von diesem Programm dargestellten Datei wird von einem extern bereitgestelltem Programm von ETAS durchgeführt. Dieses benötigt dafür jedoch einige Daten/Dateien. Neben den Bilddateien des Simulink Modells, welche ebenfalls durch ein externes Programm von ETAS generiert werden, sind drei Dateien erforderlich: eine ccx, eine slx und eine mdx Datei. Diese Dateiformate sind von ASAM (Association for Standardization of Automation and Measuring Systems), in der viele Firmen der Automobilbranchen Mitglieder sind, standardisiert und bauen alle auf dem xml-Format auf.
Die Auswahl welche Ebenen des Simulink Modells in der Dokumentation mit begleitendem Text erscheinen sollen, soll so einfach wie möglich und bevorzugt direkt in Matlab durch eine Markierung festgelegt werden. Verwendet werden hiefür Simulink Dokumentationsblöcke ("docblock"), in denen ebenfalls dem der Abbildung zugehörige Text eingetragen werden kann.
Außer wenigen Matlab Skripten die direkt auf das Modell zugreifen, sind alle anderen Skripte in Python geschrieben, da von dieser Programmiersprache von der Standardbibliothek unterstützt wird und eine ausführliche Dokumentation und Support online verfügbar ist.
Das Tool ist modular aufgebaut, sodass die einzelnen Teile einzeln entwickelt und getestet werden können und das Tool leicht modifizierbar ist, z.B. wenn eine andere Abteilung ein anderes Datenbankformat nutzt oder andere Anforderungen leicht abweichen. Die wichtigsten Bestandteile sind:
- mdx-Generierung ("ddx2mdx"): Die ddx-Quelldatei wird mit Hilfe des Python-Packages "ElementTree" geparst. Die Modifikation und das Auslesen der Daten wird dadurch erleichtert, da dieses Package die xml-Datei in eine Baumstruktur umwandelt. Der Quellbaum wird im nächsten Schritt nach den benötigten Informationen durchsucht und mit diesen der Zielbaum gemäß der mdx-Struktur aufgebaut und am Ende als Datei abgespeichert.
- ccx-Generierung ("mod_default_files.py"): Diese Datei ist in mehreren verschiedenen Projekten weitestgehend identisch und unterscheidet sich nur in wenigen Einträgen, dem Projektnamen und Pfaden der für die finale Generation benötigten Dateien). Deshalb wird hierfür keine Datei neu erstellt, sondern eine vorhandene, in der die projektspezifischen durch eindeutige Bezeichner gekennzeichnet sind, modifiziert und mittels Textersetzung die korrekten Daten eingefügt.
- fsx-Generierung ("generateFSX" und "get_dockblocks.m"): Die fsx-Generierung läuft in zwei Schritten ab. Zuerst wird von einem Matlab-Skript nach den Dokumentationsblöcken im Modell gesucht und deren Pfad und Inhalt abgespeichert. Mit diesen Informationen wird im zweiten Schritt wider mit Python die fsx-Datei aufgebaut. Ähnlich wie bei der ccx-Generierung sind einige Teile fest vorgegeben und in jedem Projekt gleich. Deshalb wird ebenfalls auf vorhandene Dateien mit eindeutigen Bezeichnern für projektspezifische Daten zurückgegriffen, die dann verändert werden, wobei es in diesem Fall drei Stück sind, die zusätzlich noch miteinander kombiniert werden müssen. In "default.fsx" ist das Grundgerüst abgespeichert, in welches für jedes Kapitel einmal eine angepasste Version der Datei "chapter.fsx" an der korrekten Stelle eingefügt wird. Ähnlich dazu wird für jede Abbildung eines Kapitels eine angepasste Version der Datei "figure.fsx" eingefügt und der dazugehörige Text eingefügt. Am Ende wird die vollständige Struktur wieder in ein Textdokument umgewandelt und abgespeichert.
- Modifikation des Simulink Modells ("mod_io.m"): Da die erste Ebene des Modells keine i/o-Ports besitzt und dies zu Defiziten in der Darstellung in der Funktionsdokumentation kommen würde, werden diese von einem Matlab Skript automatisch ergänzt. Zudem wird der Name der Datei angepasst, um der Kovention des Programmes, das am Ende die Dokumentation generiert, zu entsprechen. Da dadurch die ursprüngliche Datei modifiziert wird, wird eine Kopie des Modells im Ordner Model des Tools angelegt und so damit eventuell verbundenen Problemen an anderer Stelle vorgebeugt.
Die einzelnen Module benötigen teils Daten, die von anderen Modulen oder kleineren Skripen generiert werden. Für de Datenaustausch werden zwei config Dateien verwendet. Eine der beiden enthält alle Projektnamen und Pfade, welche automatisch von dem Skript "set_config.py" ermittelt werden, sodass kein Userinput nötig ist. Dies ist möglich, da der Projektname aus dem Pfad ausgelesen werden kann und alle anderen Namen und Pfade mit dieser Information generiert werden können. Die zweite config-Datei enthält die Informationen über die Dokumentationsblöcke des Simulink Modells, auf denen die Generierung der fsx-Datei aufbaut. Die Pfade der config-Dateien werden den Skripten, sofern benötigt, als Argument beim Aufruf übergeben, damit diese im Anschluss die benötigten Informationen auslesen können.
Zur Nutzung des Tools muss eine Batch-Datei ausgeführt werden, die alle Matlab und Python Skripte und externe Programme in der richtigen Reihenfolge aufruft. Die Ausführung dauert knapp über drei Minuten, da insgesamt zwei mal eine Matlab Instanz gestartet werden muss (Ausführen von Matlab Skripten und Generierung Bilder). Deshalb wird neben der kompletten Generierung eine verkürzte Version angeboten, in der nicht alle Skripte und Programme aufgerufen werden. In dieser Version wird nur das Modell nach Dokumentatonsblöcken durchsucht, die fsx-Datei erstellt und die Dokumentation generiert. Die anderen Daten werden von der vorherigen Generierung übernommen. Die verkürzte Version darf deshalb nur ausgeführt werden, wenn am Simulink abgesehen von den Dokumentationsblöcken nichts geändert wurde und zuvor bereits eine vollständige Funktionsdokumentation erstellt wurde.
