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.

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.