Dokumentation bei Doxygen



    Dieser Artikel ist Teil der resultierenden Artikelserie zum Doxygen-Dokumentationssystem:

    1. Code effizient mit Doxygen dokumentieren
    2. Dokumentation bei Doxygen
    3. Erstellen von Diagrammen und Diagrammen in Doxygen

    Dies ist der zweite Artikel aus dem erwähnten Zyklus, der auf den einleitenden Artikel zum Doxygen-Dokumentationssystem folgt (falls Sie mit diesem System nicht vertraut sind, empfehle ich Ihnen, diesen Artikel zu beachten und sich zumindest allgemein mit ihm vertraut zu machen). In den Kommentaren dazu wurde eine wichtige Frage zum Design der Dokumentation in Doxygen aufgeworfen, und diese Frage ist relevant, da häufig das Standarddesign verwendet wird, das zwar praktisch, aber eher schlicht wirkt.

    In diesem Artikel werde ich diese Frage beantworten. Dazu werden wir die allgemeinen Prinzipien der Doxygen-Dokumentation betrachten, sie kennenlernen und Beispiele dafür sehen, was auf dieser Basis erreicht werden kann.

    Anpassen des Erscheinungsbilds der Dokumentation


    Betrachten wir zunächst, welche Funktionen Doxygen zum Anpassen des Designs bietet (in diesem Fall sollten Sie darauf achten, dass sich die nachfolgend beschriebenen Einstellungen im Wesentlichen speziell auf das generierte HTML-Dokument beziehen). Im Allgemeinen wird dieser Abschnitt in der offiziellen Dokumentation ausführlich beschrieben , ich werde nur die wichtigsten Details darin vermerken und ihn zur Verdeutlichung mit Beispielen verdünnen.

    Designeinstellungen

    Symbol für das Projekt

    Das einfachste, was Sie im Design konfigurieren können, ist das Projektsymbol. Geben Sie dazu den Pfad zum Symbol in der Einstellungsdatei in der Option PROJECT_LOGO an :
    PROJECT_LOGO = <путь_к_иконке>
    

    Farbschema

    Um das Farbschema der HTML-Seite einfach zu ändern, werden in der Einstellungsdatei die folgenden Optionen verwendet:
    Option Wert
    HTML_COLORSTYLE_HUE Zeigt den Farbschema-Ton an.
    HTML_COLORSTYLE_SAT Zeigt die Helligkeit des Farbschemas an.
    HTML_COLORSTYLE_GAMMA Gibt den Farbumfang des Farbschemas an.
    Im Folgenden finden Sie Beispiele für dieselbe Dokumentation mit unterschiedlichen Farbschemaeinstellungen:


    Navigationshilfen

    Die Hauptnavigationswerkzeuge für die Dokumentation in Doxygen sind: Menüs mit Registerkarten und hierarchischer Baum. Sie sind unten im Screenshot dargestellt.


    Verwenden Sie die folgenden Optionen in der Einstellungsdatei, um die Anzeige dieser Elemente zu konfigurieren:
    Option Wert
    DISABLE_INDEX Deaktiviert die Menüanzeige mit Registerkarten
    GENERATE_TREEVIEW Zeigt an, ob ein hierarchischer Baum angezeigt werden soll

    Dynamischer Dokumentationsinhalt

    Um die HTML-Dokumentation interaktiver zu gestalten, bietet Doxygen eine Reihe von Optionen an, die standardmäßig deaktiviert sind:
    Option Wert
    HTML_DYNAMIC_SECTIONS Wenn diese Option aktiviert ist, reduziert Doxygen bestimmte Elemente der HTML-Dokumentation (z. B. Spalten), die der Benutzer anschließend anzeigen kann
    INTERACTIVE_SVG Wenn die grafische Darstellung mit Graphviz aktiviert und SVG als Grafikformat festgelegt ist, erstellt Doxygen interaktive SVG-Dateien, die erweitert und verschoben werden können
    Header, Footer und Cascading Style Sheet

    Um Schriftarten, Farben, Einzüge und andere Details der HTML-Dokumentation anzupassen, können Sie das Standard-Cascading-Stylesheet ändern. Darüber hinaus können Sie mit Doxygen den Titel und die Fußzeile für jede HTML-Seite ändern, die generiert wird, damit die generierte Dokumentation dem externen Stil der übrigen Website entspricht.

    Führen Sie den folgenden Befehl aus, um die entsprechenden Dateien zur weiteren Bearbeitung abzurufen:
    doxygen -w html header.html footer.html customdoxygen.css 
    

    Sie wird drei Dateien erstellen:
    1. header.html ist ein HTML-Snippet, mit dem Doxygen eine HTML-Seite startet. Bitte beachten Sie, dass dieses Fragment einige spezielle Befehle enthält, die mit einem Dollarzeichen beginnen: Sie werden beim Erstellen der Dokumentation automatisch ersetzt.
    2. footer.html ist das HTML-Snippet, mit dem Doxygen die HTML-Seite vervollständigt. Es kann auch spezielle Teams geben, die bereits erwähnt wurden.
    3. customdoxygen.css ist das Standard-Cascading-Stylesheet. Es wird empfohlen, diese Datei nur anzusehen und bestimmte Einstellungen zu ändern, indem Sie sie in einer separaten Datei ablegen.

    Nachdem Sie diese Dateien bearbeitet haben, müssen Sie Doxygen anweisen, sie beim Erstellen der Dokumentation anstelle der Standarddateien zu verwenden. Dies geschieht mit den folgenden Befehlen:
    Option Wert
    HTML_HEADER Gibt den Pfad zu der benutzerdefinierten HTML-Datei an, die den Header beschreibt (im obigen Beispiel ist dies der Pfad zu header.html).
    HTML_FOOTER Gibt den Pfad zu der benutzerdefinierten HTML-Datei an, die die Fußzeile beschreibt (im obigen Beispiel ist dies der Pfad zu footer.html).
    HTML_EXTRA_STYLESHEET Gibt den Pfad zu einem benutzerdefinierten Cascading Style Sheet an. Bitte beachten Sie, dass es zusammen mit dem Standard-Stylesheet verwendet wird und daher ausreicht, nur zu beschreiben, was Sie daran geändert haben
    Beispiel für eine Designänderung

    Als nächstes werden wir uns schöne Beispiele für verschiedene Stile und Designentscheidungen ansehen, aber im Moment werden wir nur aus Selbstvertrauen zeigen, wie wir den Stil ändern können.

    Lassen Sie uns zum Beispiel den Dokumentationstitel fett formatieren und seine Farben ändern. Erstellen Sie dazu ein style.css-Stylesheet mit dem folgenden Inhalt (Projektname ist die ID des Blocks mit dem Projektnamen. Sie können dies überprüfen, indem Sie dieselbe Datei header.html öffnen.):
    #projectname {
    	color: #3B5588;
    	font-weight: bold;
    }
    

    Geben Sie anschließend in der Einstellungsdatei unter der Option HTML_EXTRA_STYLESHEET den Pfad zur erstellten Datei an und erstellen Sie die Dokumentation. Das Ergebnis sieht folgendermaßen aus (die vorherige Option wird zum Vergleich angezeigt):


    Auf die gleiche Weise können Sie den Stil aller anderen Elemente ändern.

    Einrichten der Dokumentationsstruktur


    Zuvor haben wir untersucht, wie Sie das Erscheinungsbild der Dokumentation ändern können. Eine Änderung hat jedoch keine Auswirkungen auf die Struktur der Dokumentation.

    Verwenden Sie dazu eine spezielle Datei, die die Struktur des Dokuments mithilfe der XML-Auszeichnungssprache beschreibt. Doxygen verwendet es dann, um zu bestimmen, welche Informationen in welcher Reihenfolge angezeigt werden müssen und teilweise auch, wie sie angezeigt werden sollen.

    Ähnlich wie beim Ändern des Dokumentationsdesigns müssen Sie zuerst die verwendete Standarddatei abrufen. Verwenden Sie dazu den Befehl -l (aus dem Layout):
    doxygen -l [имя_файла]
    

    Die oberste Ebene dieser Datei lautet wie folgt:
    
        ...
      
        ...
      
        ...
      
        ...
      
        ...
      
        ...
      

    Einzelheiten zum Arbeiten mit dieser Struktur sind im entsprechenden Abschnitt der offiziellen Dokumentation beschrieben.

    Wir stellen nur fest, dass Sie nach dem Erstellen Ihrer Datei die Option LAYOUT_FILE in der Einstellungsdatei ändern müssen, um den Pfad zu dieser Datei anzugeben:
    LAYOUT_FILE = <путь_к_файлу>
    

    Beispiel für eine Strukturänderung

    Um wieder Vertrauen in unsere Fähigkeiten zu gewinnen, werden wir diese Struktur geringfügig ändern.

    Zunächst generieren wir eine Datei mit einer Struktur (wie oben beschrieben) und fügen dann eine neue Registerkarte zum Menü hinzu. Registerkarten werden mithilfe des Registerkarten- Tags hinzugefügt. In diesem Fall müssen Sie beim Hinzufügen einer neuen Registerkarte den Benutzertyp angeben .

    Da wir dem Menü einen Tab hinzufügen möchten, müssen wir den entsprechenden Abschnitt suchen (für das Menü ist es navindex ) und unseren Tab hinzufügen:
    
           ...
           

    Achten Sie auf den Wert der URL- und Titelparameter , der erste bietet einen Übergang zu habrahabr.ru, wenn Sie auf diese Registerkarte klicken, und der zweite spiegelt den Text auf der Registerkarte wider.

    Das Ergebnis sieht dann so aus:


    Dokumentationsbeispiele


    Nachdem wir herausgefunden hatten, wie die Dokumentation zu erstellen ist, war es an der Zeit, sich vorgefertigte Beispiele anzusehen, die Sie für Ihre Projekte verwenden können.

    Qt4-Thema

    Unten finden Sie eine Beispieldokumentation, die auf der Grundlage eines Themas erstellt wurde, das die Qt- Dokumentation der vierten Version kopiert .


    Bootstrap-Thema

    Ein Theme wurde speziell für Bootstrap- Fans erstellt .


    Noch zwei Beispiele

    Über den folgenden Link können Sie sich mit zwei Themen zur Dokumentation vertraut machen und diese herunterladen.



    Fazit


    Zusammenfassend möchte ich festhalten, dass es ziemlich schwierig war, fertige Themen für die Dokumentation zu finden, aber tatsächlich ist die Funktionalität, die Doxygen zum Anpassen des Designs bietet, sehr umfangreich und erleichtert das Anpassen der Dokumentation nach Ihrem Geschmack. Ich hoffe, dass dieser Artikel Ihnen dabei helfen wird Ihre Dokumentation ist schöner und angenehmer für den Leser.

    Vielen Dank für Ihre Aufmerksamkeit!

    Jetzt auch beliebt: