QDoc-Konfigurationsdateien erstellen
Um Dokumentation zu erstellen, verwendet QDoc Konfigurationsdateien mit der Erweiterung qdocconf
, um Konfigurationseinstellungen zu speichern.
Der Artikel Die QDoc Konfigurationsdatei behandelt die verschiedenen Konfigurationsvariablen im Detail.
QDoc Konfigurationsdateien
Die Konfigurationseinstellungen von QDoc können in einer einzelnen qdocconf Datei stehen, aber auch in anderen qdocconf Dateien. Das include(<filepath>)
Kommando erlaubt es Konfigurationsdateien, andere Konfigurationsdateien einzubinden.
QDoc hat zwei Ausgaben, HTML-Dokumentation und Dokumentation im DocBook XML-Format. Der Hauptunterschied zwischen den beiden Ausgaben ist, dass die HTML-Dokumentation ihre HTML-Styling-Informationen in den Konfigurationsdateien haben muss. Bei der DocBook-Dokumentation ist dies nicht der Fall, und ein separater Prozess kann die Dokumentation in DocBook zu einem späteren Zeitpunkt gestalten. DocBook ist daher flexibler und erlaubt die Anwendung verschiedener Stile auf dieselben Informationen.
Um QDoc zu starten, wird die Projektkonfigurationsdatei als Argument übergeben.
qdoc project.qdocconf
Die Projektkonfiguration enthält Informationen, die QDoc zur Erstellung der Dokumentation verwendet.
Projekt-Informationen
QDoc verwendet die Informationen von project
, um die Dokumentation zu erstellen.
project = QDoc Project description = Sample QDoc project
Eingabe- und Ausgabeverzeichnisse
Die Angabe des Pfades zu den Quellverzeichnissen ermöglicht es QDoc, die Quellen zu finden und die Dokumentation zu erzeugen.
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 Kopfzeilen und Quellen aus den Verzeichnissen, die in der Variable fileextensions
angegeben sind.
Gleichermaßen benötigt QDoc den Pfad zum Ausgabeverzeichnis. Die Variable outputformats
bestimmt den Typ der Dokumentation. Diese Variablen sollten in separaten Konfigurationsdateien stehen, um die Erstellung der Dokumentation zu modularisieren.
outputdir = $SAMPLE_PROJECT/doc/html outputformats = HTML
QDoc kann sowohl die Pfade relativ zur qdocconf-Datei als auch Umgebungsvariablen auflösen.
Hinweis: Bei jedem QDoc-Lauf wird das Ausgabeverzeichnis gelöscht.
Extra Dateien
QDoc gibt die generierte Dokumentation in das im Ausgabeverzeichnis angegebene Verzeichnis aus. Es ist auch 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 auch eine Qt Help Projektdatei, in eine qhp
Datei. Die qhp-Datei wird dann von qhelpgenerator
verwendet, um die Dokumentation in eine qch
-Datei zu packen. Qt Creator und Qt Assistant lesen die qch-Datei, um die Dokumentation anzuzeigen.
Der Artikel Erstellen von Hilfeprojektdateien behandelt die Konfigurationsoptionen.
HTML-Konfiguration
QDoc verfügt über einen HTML-Generator, der eine Reihe von Dokumentationen unter Verwendung verschiedener Konfigurationseinstellungen in HTML-Dateien exportiert. QDoc legt die generierte Dokumentation in dem Verzeichnis ab, das durch die Variable outputdir
festgelegt ist.
outputformats = HTML outputdir = <path to output directory>
QDoc muss wissen, wo sich die Stile und Vorlagen für die Erzeugung von HTML befinden. Normalerweise enthält das Templates-Verzeichnis ein scripts
, images
und ein style
Verzeichnis, das Skripte und CSS-Dateien enthält.
Die wichtigsten Konfigurationsvariablen sind:
HTML.postheader HTML.postpostheader HTML.postheader 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
gibt an, welche Dateien QDoc in das Ausgabeverzeichnis kopieren soll. Außerdem bettet QDoc die Zeichenfolge in den Variablen postheader
, footer
und verwandten Variablen in jede HTML-Datei ein.
Der Artikel Formatspezifische Konfigurationsvariablen beschreibt die Verwendung der einzelnen Variablen.
QDoc Index Dateien
Dokumentationsprojekte können auf Ziele in anderen Projekten verlinken, indem sie einen Satz von Abhängigkeiten oder einen Satz von direkten Pfaden zu Indexdateien angeben, von denen das Projekt abhängt. Wenn QDoc Dokumentation für ein Projekt generiert, wird es auch eine .index
Datei erzeugen, die URLs zu jeder verlinkbaren Entität im Projekt enthält. Andere Projekte können dann eine Abhängigkeit zur Indexdatei definieren, um auf die Dokumentation innerhalb dieses Projekts zu verlinken.
Siehe auch: depends und indexes.
Makros und andere Konfigurationen
Es gibt Makros zur Ersetzung von HTML-Zeichen, die hilfreich sind, um bestimmte HTML-valide Zeichen zu erzeugen.
macro.pi.HTML = "Π"
Der Code des Schnipsels ersetzt alle Instanzen von \\pi
durch &Pi
; in der HTML-Datei, was in Browsern als griechisches Π-Symbol erscheint.
Siehe auch: Makro.
QML-Zusätze
QDoc ist in der Lage, QML-Dateien für QDoc-Kommentare zu analysieren. QDoc analysiert Dateien mit der QML-Erweiterung .qml
, wenn der Erweiterungstyp in der Variable fileextensions enthalten ist.
Außerdem können die generierten HTML-Dateien ein Präfix und ein Suffix nach dem QML-Modulnamen haben, die in der QDoc-Konfigurationsdatei angegeben sind.
outputprefixes = QML outputprefixes.QML = uicomponents- outputsuffixes = QML outputsuffixes.QML = -tp
Siehe auch: outputprefixes, outputsuffixes.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.