Die QDoc-Konfigurationsdatei

Bevor Sie QDoc ausführen, müssen Sie eine QDoc-Konfigurationsdatei erstellen, um QDoc mitzuteilen, wo sich die Quelldateien befinden, die die QDoc-Kommentare enthalten. Der Pfad zu Ihrer Konfigurationsdatei wird über die Befehlszeile an QDoc übergeben:

/current/dir$ ../../bin/qdoc ./config.qdocconf

Allgemeine Beschreibung

Die Konfigurationsdatei besteht aus einer Liste von Einträgen in der Form „Variable = Wert“. Mithilfe der Konfigurationsvariablen können Sie festlegen, wo QDoc die verschiedenen Quelldateien, Bilder und Beispiele finden soll, wo die generierte Dokumentation abgelegt werden soll usw. Die Konfigurationsdatei kann auch Anweisungen wie „ include “ enthalten. Ein Beispiel finden Sie in der Datei „minimum.qdocconf“.

Sie können Konfigurationsvariablen auch verwenden, um QDoc dazu zu bringen, abgeleitete Projekte zu unterstützen, d. h., QDoc kann in der Dokumentation Ihres Projekts Verweise auf Elemente in der Qt-Online-Dokumentation generieren. Siehe den Abschnitt „Unterstützung abgeleiteter Projekte “.

Ein gültiger Name für eine Konfigurationsvariable kann Groß- und Kleinbuchstaben, Zahlen und einen Unterstrich („_“) enthalten.

Der Wert einer Konfigurationsvariablen kann entweder mit „=“ oder „+=“ festgelegt werden. Der Unterschied besteht darin, dass „=“ den bisherigen Wert überschreibt, während „+=“ den aktuellen Wert um einen neuen Wert ergänzt.

Die Werte einiger Konfigurationsvariablen werden als Liste von Zeichenketten interpretiert, zum Beispiel: sourcedirs, während andere als einzelne Zeichenkette behandelt werden. Doppelte Anführungszeichen um eine Wertzeichenkette sind optional, ermöglichen es Ihnen jedoch, Sonderzeichen wie „=“ und „ " “ innerhalb der Wertzeichenkette zu verwenden, zum Beispiel:

HTML.postheader = "<ul class=\"breadcrumbs\">"

Wenn sich ein Eintrag über mehrere Zeilen erstreckt, verwenden Sie am Ende jeder Zeile außer der letzten einen Backslash:

sourcedirs = kernel tools widgets

Dies lässt sich wie folgt schreiben:

sourcedirs = kernel \
             tools \
             widgets

Wenn ein Wert sich über mehrere Zeilen erstreckt, aber als einzelne Zeichenkette interpretiert wird, werden die Zeilen durch Leerzeichen verbunden.

Erweiterung von Konfigurationswerten

QDoc unterstützt die Erweiterung von Umgebungsvariablen in Konfigurationsdateien. Beispielsweise nutzen Qt-Module die Umgebungsvariable QT_INSTALL_DOCS, um Definitionen einzubinden, die sich auf alle Qt-Modul-Dokumentationsprojekte beziehen:

include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)

Eine zu expandierende Variable wird mit einem „$“ eingeleitet. Um das Literalzeichen „$“ innerhalb einer Wertzeichenfolge zu verwenden, muss es mit einem Backslash maskiert werden: „\$“.

Seit QDoc 6.0 können Werte auch aus anderen Konfigurationsvariablen erweitert werden. Neben der Syntax „ $variable “ ist auch „ ${variable} “ gültig. Letzteres macht es überflüssig, den Variablennamen durch Leerzeichen oder Nicht-Variablenzeichen zu trennen. Zum Beispiel:

baseurl = https://doc.qt.io/
...
url = ${baseurl}qtcreator

Bezieht sich die Zielvariable auf eine Liste von Zeichenfolgen, werden diese im erweiterten Wert durch Leerzeichen verbunden:

vars = foo \
       bar \
       baz

items = "Items: $vars"          # Expands to "Items: foo bar baz"

Es ist auch möglich, zu steuern, welches Zeichen zum Verknüpfen der Zeichenfolgenliste verwendet wird:

items = "Items: ${vars,|}"      # Expands to "Items: foo|bar|baz"
items = "Items: ${vars,,}"      # Expands to "Items: foo,bar,baz"
items = "Items: ${vars,}"       # Expands to "Items: foobarbaz"

Da die Erweiterung erst nach dem Einlesen aller Variablen erfolgt, spielt die Reihenfolge, in der sie definiert sind, keine Rolle.

Erweiterung von Umgebungsvariablen

Bei der Erweiterung von Umgebungsvariablen verhält sich die Syntax „ ${variable} “ anders als „ $variable “. Ersteres erweitert den Inhalt der Variablen an Ort und Stelle, sodass er als Teil der Konfigurationsdatei geparst wird, während Letzteres den Inhalt lediglich als Wert für die aktuelle Konfigurationsvariable zuweist. Dies hat Auswirkungen, wenn die Umgebungsvariable eine Liste von Elementen enthält, die durch Leerzeichen oder andere von QDoc erkannte Formatierungen getrennt sind.

Wenn beispielsweise der Wert der Umgebungsvariablen „ SRCDIRS “ „ "../src/a ../src/b" “ lautet, dann

sourcedirs  = $SRCDIRS      # Fail - value is interpreted as a single path.
sourcedirs  = ${SRCDIRS}    # Ok - whitespace is used as a delimiter.

Konfigurationsvariablen

Variablenliste

• definiert
• depends
• Dokumentation in Kopfzeilen
• Beispielverzeichnisse
• Beispiele
• BeispieleInstallationspfad
• Beispiele.Dateierweiterungen
• Beispiele.Warnung bei fehlenden Bildern
• Beispiele.Warnung bei fehlenden Projektdateien
• ausgeschlossene Verzeichnisse
• ausgeschlossene Dateien
• zusätzliche Bilder
• Unwahrheiten
• Kopfzeilenverzeichnisse
• Kopfzeilen
• Kopfzeilen.Dateiendungen
• HTML.Fußzeile
• HTML.Beitragskopfzeile
• HTML.Beitrags-Nachkopf
• HTML.style
• Einbindepfade
• includeprivate
• ignorierte Wörter
• ignoresince
• Bildverzeichnisse
• Ausgabeverzeichnis für Bilder
• Indizes
• Sprache
• Standortinformationen
• Logwarnungen
• Makro
• Manifest-Metadaten
• Modul-Kopfzeile
• Navigation
• Ausgabeverzeichnis
• Ausgabeformate
• Ausgabevoranstellungen
• Ausgabe-Endungen
• parsecpp-Kommentare
• vorläufig
• Produktname
• Projekt
• Projektstammverzeichnis
• Automatisch generierte Dokumentation anzeigen
• Quellverzeichnisse
• Quellen
• Quelldateierweiterungen
• spurious
• Tabulatorgröße
• URL
• URL-Beispiele
• URL-Quellen
• alternativen Text als Titel verwenden
• version
• versionsym
• Warnungsgrenze

Kategorien

• Allgemeine Konfigurationsvariablen
• Formatspezifische Konfigurationsvariablen

Beispiele für Konfigurationsdateien

• Eine minimale Konfigurationsdatei: minimum.qdocconf
• Die Qt-Konfigurationsdatei: qtgui.qdocconf