Vor einiger Zeit hatte ich mich mal aufgemacht um meine Bash-Dateien, welche ich täglich verwende mal sauber zu dokumentieren. Dabei habe ich verschiedene Lösungen ausprobiert (von selbstgebauten bis zu kostenpflichtigen) und bin letztendlich bei Doxygen hängen geblieben. Doygen kann jedoch von Haus aus nicht mit bash Dateien umgehen. In diesem Beitrag zeige ich wie man das löst und Doxygen dafür vorbereitet.
Los geht es mit der Installation von Doxygen welche je nach Distro unterschiedlich ist. Ich bin mit der manuellen Kompilierung ganz gut gefahren, aber das kommt auf den Nutzer an ;) So habe ich zunächst hier die Anweisungen für die “Bleeding Edge” Version nachgesehen und durchgeführt.
|
|
An dieser Stelle sollte sich unter:
|
|
schon das binary melden können ;)
Nun geht es an die Einbindung des Bash Dokumentationsplugins. Dazu verwende ich bash-doxygen was ein Filter, in sed umgesetzt, ist und die Dateien von Bash auf C-Code (was doxygen versteht) umsetzt.
Zunächst muss man sich einen Ort raussuchen unter dem das Plugin zu finden ist. Der Author selbst hat das Plugin unter die WTFPL gestellt, wodurch es auch direkt im Sourcecode mitgeliefert werden kann. Ich habe das bei meinem Projekt so gelöst, dass ich den Filter in einem Unterordner gehalten habe. Um das einfach darzustellen zeige ich mal wie mein Projekt aufgebaut ist.
Zunächst habe ich ein Verzeichnis in dem eine bash-Datei liegt, die dokumentiert werden soll. Das ganze sieht dann so aus:
- myfile.sh
- docs
- generate.sh
- helpers
- bash-doxygen
- doxygen-bash.sed
- bash-doxygen
- docs
Oder als Kommandos:
|
|
Nun steht die Struktur aber man muss noch das Konfigurationsfile für Doxygen unter docs/Doxyfile anpassen. Dazu editiert man dieses - im Nachfolgenden gebe ich die wichtigsten Änderungen an, welche ich durchgeführt habe:
PROJECT_NAME Hier habe ich den Namen meines Projektes eingetragen - dieser erscheint dann in der Titelzeile der Dokumentation.
PROJECT_NUMBER
1
PROJECT_NUMBER = $(PROJECT_NUMBER)
Diese Projektnummer wird via Umgebungsvariable in der generate.sh gesetzt und kann beispielsweise ein git commit oder das aktuelle Datum sein.
PROJECT_BRIEF Ein schlagkräftiger Satz zur Beschreibung. Wird im Header der Dokumentation angezeigt.
EXTENSION_MAPPING
1
EXTENSION_MAPPING = sh=C
um die sh Dateien parsen zu lassen
INPUT
1
INPUT = ../
da der übergeordnete Ordner geparsed werden soll
FILE_PATTERNS Füge das Pattern
1
*.sh
mit hinzu, damit Doxygen diese Files ansieht
RECURSIVE
1
RECURSIVE = YES
da auch untergeordnete Ordner geparsed werden sollen
EXCLUDE_PATTERNS
1
EXCLUDE_PATTERNS = */docs/*
Alle Ordner, die “docs” im Namen beinhalten sollen nicht geparsed werden
INPUT_FILTER
1
INPUT_FILTER = "sed -n -f helpers/bash-doxygen/doxygen-bash.sed -- "
Damit fehlt dann nur noch das myfile.sh. Hier ein Quickstarter als Template für bashfiles:
|
|
Wie man sehen ( und der Doku entnehmen kann ) müssen die Teile, welche an Doxygen weitergegeben werden, mit zwei Rauten versehen werden. Zudem werden Variablen mit “ declare ” versehen und Funktionen müssen ohne “function” keyword und mit der öffnenden Klammer in der ersten Zeile geschrieben und mit @fn versehen versehen werden. Die Hauptdatei kann man zusätzlich mit einer Beschreibung des Projekts (@mainpage) versehen werden. Dokumentation kann dann entweder regulär oder mit Markdown geschrieben werden. Und statt “@” kann man auch “" als keyword verwenden. Alle keywords sind hier beschrieben.
Eigentlich easy ;)