Erstellen von QDoc-Konfigurationsdateien

Um Dokumentation zu generieren, verwendet QDoc Konfigurationsdateien mit der Erweiterung „ qdocconf “, in denen die Konfigurationseinstellungen gespeichert werden.

Der Artikel „Die QDoc-Konfigurationsdatei“ behandelt die verschiedenen Konfigurationsvariablen ausführlicher.

QDoc-Konfigurationsdateien

Die Konfigurationseinstellungen von QDoc können in einer einzigen qdocconf-Datei gespeichert sein, aber auch in mehreren qdocconf-Dateien. Mit dem Befehl „ include(<filepath>) “ können Konfigurationsdateien andere Konfigurationsdateien einbinden.

QDoc bietet zwei Ausgabeformate: HTML-Dokumentation und Dokumentation im DocBook-XML-Format. Der wesentliche Unterschied zwischen den beiden Ausgabeformaten besteht darin, dass für die HTML-Dokumentation die HTML-Formatierungsinformationen in den Konfigurationsdateien enthalten sein müssen. Bei der DocBook-Dokumentation ist dies nicht der Fall, und die Formatierung der Dokumentation im DocBook-Format kann zu einem späteren Zeitpunkt in einem separaten Prozess erfolgen. DocBook ist daher flexibler, da es die Anwendung unterschiedlicher Stile auf dieselben Informationen ermöglicht.

Um QDoc auszuführen, wird die Projektkonfigurationsdatei als Argument übergeben.

qdoc project.qdocconf

Die Projektkonfiguration enthält Informationen, die QDoc zur Erstellung der Dokumentation verwendet.

Projektinformationen

QDoc verwendet die Informationen aus „ project “, um die Dokumentation zu generieren.

project = QDoc Project
description = Sample QDoc project

Eingabe- und Ausgabeverzeichnisse

Durch die Angabe des Pfads zu den Quellverzeichnissen kann QDoc die Quelldateien finden und die Dokumentation erstellen.

sourcedirs = <path to source code>
exampledirs = <path to examples directory>
imagedirs = <path to image directory>

sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"

QDoc verarbeitet Header- und Quelldateien aus den in der Variablen „ fileextensions “ angegebenen Verzeichnissen.

Ebenso benötigt QDoc den Pfad zum Ausgabeverzeichnis. Die Variable ` outputformats ` legt die Art der Dokumentation fest. Diese Variablen sollten in separaten Konfigurationsdateien gespeichert werden, um den Dokumentationsaufbau zu modularisieren.

outputdir  =    $SAMPLE_PROJECT/doc/html
outputformats = HTML

QDoc kann die Pfade sowohl relativ zur qdocconf-Datei als auch anhand von Umgebungsvariablen auflösen.

Zusätzliche Dateien

QDoc speichert die generierte Dokumentation in dem unter „Ausgabeverzeichnis“ angegebenen Verzeichnis. Es ist außerdem möglich, zusätzliche Dateien anzugeben, die QDoc exportieren soll.

HTML.extraimages = extraImage.png \
                   extraImage2.png

Die Dateien „ extraImage.png “ und „ extraImage2.png “ werden in das HTML-Ausgabeverzeichnis kopiert.

Qt Help Framework-Konfiguration

QDoc exportiert außerdem eine Qt Help -Projektdatei in Form einer qhp -Datei. Die qhp-Datei wird anschließend vom qhelpgenerator verwendet, um die Dokumentation in eine qch -Datei zu verpacken. Qt Creator und Qt Assistant lesen die qch-Datei ein, um die Dokumentation anzuzeigen.

Der Artikel „Erstellen von Hilfe-Projektdateien“ behandelt die Konfigurationsoptionen.

HTML-Konfiguration

QDoc verfügt über einen HTML-Generator, der anhand verschiedener Konfigurationseinstellungen eine Dokumentation in HTML-Dateien exportiert. QDoc speichert die generierte Dokumentation in dem Verzeichnis, das durch die Variable „ outputdir “ angegeben wird.

outputformats = HTML
outputdir =  <path to output directory>

QDoc muss wissen, wo sich die Stile und Vorlagen für die HTML-Generierung befinden. In der Regel enthält das Verzeichnis „templates“ die Unterverzeichnisse „ scripts “, „ images “ und „ style “, in denen Skripte und CSS-Dateien gespeichert sind.

Die wichtigsten Konfigurationsvariablen sind:

HTML.postheader
HTML.postpostheader
HTML.footer

HTML.headerstyles
HTML.stylesheets = template/style/style.css \
                   template/style/style1.css

HTML.scripts = template/scripts/script.js

Die Variable „ HTML.headerstyles “ fügt die Stilinformationen in die HTML-Datei ein, und die Variable „ HTML.stylesheets “ legt fest, welche Dateien QDoc in das Ausgabeverzeichnis kopieren soll. Darüber hinaus bindet QDoc die Zeichenfolge aus den Variablen „ postheader “, „ footer “ und den zugehörigen Variablen in jede HTML-Datei ein.

Der Artikel „Formatspezifische Konfigurationsvariablen“ beschreibt die Verwendung der einzelnen Variablen.

QDoc-Indexdateien

Dokumentationsprojekte können auf Ziele in anderen Projekten verweisen, indem sie eine Reihe von Abhängigkeiten oder direkte Pfade zu Indexdateien angeben, von denen dieses Projekt abhängt. Wenn QDoc Dokumentation für ein Projekt generiert, erstellt es außerdem eine „ .index “-Datei, die URLs zu allen verlinkbaren Elementen im Projekt enthält. Andere Projekte können dann eine Abhängigkeit zu dieser Indexdatei definieren, um auf die Dokumentation innerhalb dieses Projekts zu verweisen.

Siehe auch: „depends “ und „indexes“.

Makros und andere Konfigurationen

Es gibt Makros zum Ersetzen von HTML-Zeichen, die bei der Generierung bestimmter HTML-konformer Zeichen hilfreich sind.

macro.pi.HTML         = "Π"

Der Codeausschnitt ersetzt alle Vorkommen von „ \\pi “ durch „ &Pi “ in der HTML-Datei, was in Browsern als griechisches Π-Symbol angezeigt wird.

Siehe auch: Makro.

Ergänzungen zu QML

QDoc kann QML-Dateien nach QDoc-Kommentaren durchsuchen. QDoc analysiert Dateien mit der QML-Erweiterung ( .qml), sofern der Erweiterungstyp in der Variablen `fileextensions ` enthalten ist.

Außerdem können die generierten HTML-Dateien ein Präfix und ein Suffix enthalten, die dem QML-Modulnamen folgen und in der QDoc-Konfigurationsdatei festgelegt sind.

outputprefixes = QML
outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp

Siehe auch: ` outputprefixes`, ` outputsuffixes`.