Doxygen

Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:

Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:

  1. Anwendungen hinzufügen

  2. Installation von Programmen

  3. Archive entpacken

  4. Ein Terminal öffnen

  5. Einen Editor öffnen

  6. Programme zum Menü hinzufügen

  7. Ein Programm starten

Inhaltsverzeichnis
  1. Installation
    1. Aus den Ubuntu-Paketquellen
    2. Download von der Projektseite
  2. Benutzung
    1. Terminal
    2. Grafische Benutzeroberfläche
    3. Wichtige Einstellungen
  3. Links

doxygen-logo.pngDoxygen 🇬🇧 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. Zur Zeit (Stand 19.04.2014) 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:

Paketliste zum Kopieren:

sudo apt-get install doxygen doxygen-doc doxygen-gui graphviz 

Oder mit apturl die Pakete 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

doxywizard.pngZur 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.