Doxygen
Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:
Ubuntu 22.04 Jammy Jellyfish
Du möchtest den Artikel für eine weitere Ubuntu-Version testen? Mitarbeit im Wiki ist immer willkommen! Dazu sind die Hinweise zum Testen von Artikeln zu beachten.
Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:
Doxygen 🇬🇧 ist ein freies Werkzeug zur Softwaredokumentation. Durch spezielle Kommentare im Quellcode, erstellt Doxygen eine Dokumentation in HTML, LaTeX, CHM (Hilfedateien unter Windows), XML, RTF, PostScript, PDF und Manpages. Dabei analysiert Doxygen sowohl die Kommentare, als auch den Quellcode selbst, um Module, Klassen, Methoden und Funktionen sowie verschiedene Arten von Variablen zu erkennen und zu dokumentieren.
Da Doxygen den Quellcode analysiert, muss es in der Lage sein, die jeweilige Syntax zu erkennen. Unter anderem werden offiziell C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#, TCL und teilweise D unterstützt.
Installation¶
Aus den Ubuntu-Paketquellen¶
Die folgenden Pakete können direkt aus den Ubuntu-Paketquellen installiert [1] werden:
doxygen
doxygen-doc (Dokumentation, optional)
doxygen-gui (universe - Grafische Benutzeroberfläche auf Basis von Qt, optional)
graphviz (Benötigt zur Erstellung von Diagrammen; z.B. Kollaborationsdiagramm, optional)
Befehl zum Installieren der Pakete:
sudo apt-get install doxygen doxygen-doc doxygen-gui graphviz
Oder mit apturl installieren, Link: apt://doxygen,doxygen-doc,doxygen-gui,graphviz
Hinweis:
Das Paket doxygen empfiehlt die Installation des Paktes doxygen-latex. Unter Ubuntu werden empfohlene Pakte automatisch mitinstalliert. Falls man keine Dokumentation mit LaTeX erstellen möchte, kann man sich die Installation von doxygen-latex (ca. 450 Mb) mit folgendem Befehl im Terminal [4] sparen:
sudo apt-get install --no-install-recommends doxygen doxygen-gui
Download von der Projektseite¶
Unter Umständen enthält die offizielle Paketquelle von Ubuntu nicht die neuste Version von Doxygen. Benötigt man die aktuellste Version, kann man diese auf der Downloadseite des Projekts ⮷ herunterladen. Der Download beinhaltet lediglich das Hauptprogramm, die grafische Benutzeroberfläche ist nicht enthalten. Nachdem man das dort angebotene Archiv herunter geladen und entpackt[3] hat, ist es direkt einsatzbereit.
Benutzung¶
Der erste Schritt zur Benutzung von Doxygen ist die Kommentierung des zu dokumentierenden Quellcodes. Diese sollte sowohl in Hinblick auf die spätere Dokumentation, als auch für einen selbsterklärenden Quellcode geschehen. Da für die verschiedenen Programmiersprachen teilweise unterschiedliche Kommentare und Funktionen zur Verfügung stehen, sei hier lediglich auf die Dokumentation verwiesen 🇬🇧.
Terminal¶
Nachdem der Quellcode kommentiert wurde, kann die Dokumentation erstellt werden. Dazu wird wird ein Terminal geöffnet[4] und dort in einem beliebigen Verzeichnis folgender Befehl ausgeführt:
doxygen -g TEST
Dadurch wird eine Konfigurationsdatei mit dem Namen TEST erstellt. Diese gilt es nun mit einem beliebigen Texteditor[5] zu bearbeiten. In der Regel können dabei die meisten Einstellungen beibehalten werden. Einige Konfigurationsparameter werden im Abschnitt Wichtige Einstellungen aufgeführt.
Um nun die Dokumentation zu erstellen, wird folgender Befehl in der Terminal ausgeführt:
doxygen TEST
Nachdem das Programm durchgelaufen ist, befindet sich, je nach gewähltem Dokumentationsformat, im aktuellen Ordner ein neuer Unterordner. Wurde beispielsweise eine HTML-Dokumentation erstellt, wurde ein Verzeichnis mit dem Namen html erstellt. Die sich darin befindende Datei index.htm, kann nun mit einem beliebigen Browser angezeigt werden. Um die Dokumentation zu veröffentlichen, müssen natürlich alle im Ordner html befindlichen Dateien veröffentlicht werden.
Grafische Benutzeroberfläche¶
Zur Verwendung der grafischen Benutzeroberfläche, muss das oben genannte Paket installiert werden. Nach der Installation wird kein Menüeintrag erstellt. Dies kann man jedoch manuell nachholen[6] oder die Anwendung im Terminal mit dem Befehl doxywizard starten[7].
Doxywizard fasst alle Konfigurationsparameter auf Englisch in einer grafischen Benutzeroberfläche zusammen. Es werden zwei Vorgehensweisen zur Konfiguration angeboten. Der Reiter "Wizard" bietet nur die grundlegenden Einstellungsmöglichkeiten an und ermöglicht es Einsteigern leicht und schnell Doxygen zu konfigurieren. Benötigt man diverse Feineinstellungen und kennt sich mit Doxygen aus, wählt man den Reiter "Expert". Alle zur Verfügung stehenden Parameter werden inklusive eines kurzen Erklärungstextes angezeigt und nach Themen gruppiert aufgelistet.
Nachdem man alle gewünschten Einstellungen vorgenommen hat, wechselt man auf den Reiter "Run" und kann die Erstellung der Dokumentation über die Schaltfläche "Run doxygen" starten. Je nachdem welches Format für die Dokumentation ausgewählt wurde, befindet sich im Projektverzeichnis ein entsprechender Unterordner (z.B. html).
Wichtige Einstellungen¶
| Konfiguration von Doxygen | |
| Name der Option | Beschreibung |
PATH | Pfad zum Quellcode-Verzeichnis des Projektes |
RECURSIVE | Yes/No - Verzeichnisse rekursiv durchsuchen |
EXCLUDE | Liste von Verzeichnissen / Dateien, die nicht durchsucht werden sollen. |
ALL_MODULES | Auf Yes setzen, falls auch Module und Klassen aufgeführt werden sollen, die noch keine Doxygen-Formatierung enthalten. |
OUTPUT_LANGUAGE | Sprache der Dokumentation (z.B. English, German, ...) |
Eine ausführliche Liste aller Parameter, ist auf dieser Seite 🇬🇧 zu finden.
Links¶
Alternativen:
Javadoc - HTML-Dokumentationsseiten für Java-Quellcode erstellen
PhpDocumentor - Freies Dokumentationswerkzeug für PHP-Code
Natural Docs - Freies Dokumentationswerkzeug (Sprachunterstützung: C#, Perl, ActionScript 2, C, C++, Java, PHP, Python, PL/SQL, Visual Basic, Pascal / Delphi, Ada, JavaScript, Ruby, Tcl, ColdFusion, Assembler, Fortran, R, Makefiles, Plain text und selbst entwickelte Sprachen)