Die QDoc-Konfigurationsdatei

Bevor Sie QDoc starten, müssen Sie eine QDoc-Konfigurationsdatei erstellen, um QDoc mitzuteilen, wo es die Quelldateien finden soll, die die QDoc-Kommentare enthalten. Der Pfadname zu Ihrer Konfigurationsdatei wird QDoc auf der Kommandozeile übergeben:

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

Allgemeine Beschreibung

Die Konfigurationsdatei ist eine Liste von Einträgen in der Form "Variable = Wert". Mit Hilfe 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 Direktiven wie include enthalten. Für ein Beispiel siehe minimum.qdocconf.

Sie können auch Konfigurationsvariablen verwenden, um QDoc dazu zu bringen, abgeleitete Projekte zu unterstützen, d.h. QDoc kann in der Dokumentation Ihres Projekts Links zu Elementen in der Qt-Online-Dokumentation erzeugen. Siehe den Abschnitt Unterstützung von abgeleiteten Projekten.

Ein gültiger Konfigurationsvariablenname kann Groß- und Kleinbuchstaben, Zahlen und einen Unterstrich '_' enthalten.

Der Wert einer Konfigurationsvariablen kann entweder mit '=' oder '+=' gesetzt werden. Der Unterschied besteht darin, dass '=' den vorherigen Wert überschreibt, während '+=' einen neuen Wert zum aktuellen Wert hinzufügt.

Die Werte einiger Konfigurationsvariablen werden als eine Liste von Zeichenketten interpretiert, zum Beispiel: sourcedirs, während andere als eine einzige Zeichenkette behandelt werden. Doppelte Anführungszeichen um eine Zeichenkette sind optional, aber wenn Sie sie einschließen, können Sie Sonderzeichen wie '=' und ' " ' innerhalb der Zeichenkette verwenden:

HTML.postheader = "<a href=\"index.html\">Home</a>"

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

sourcedirs = kernel tools widgets

Dies kann wie folgt geschrieben werden:

sourcedirs = kernel \
             tools \
             widgets

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

Erweiterung von Konfigurationswerten

QDoc unterstützt die Erweiterung von Umgebungsvariablen in Konfigurationsdateien. Qt-Module verwenden zum Beispiel die Umgebungsvariable QT_INSTALL_DOCS, um Definitionen für alle Qt-Modul-Dokumentationsprojekte einzuschließen:

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

Eine zu erweiternde Variable wird mit dem Präfix '$' versehen. Um das Zeichen '$' in einer Zeichenkette zu verwenden, muss es mit einem Backslash getrennt werden: '\$'.

Seit QDoc 6.0 können Werte auch aus anderen Konfigurationsvariablen expandiert werden. Neben der $variable -Syntax ist auch ${variable} gültig. Bei letzterer entfällt die Notwendigkeit, den Variablennamen mit Leerzeichen oder Nicht-Variablen-Zeichen zu trennen. Ein Beispiel:

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

Wenn sich die Zielvariable auf eine Liste von Zeichenketten bezieht, werden diese im erweiterten Wert durch Leerzeichen verbunden:

vars = foo \
       bar \
       baz

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

Es kann auch gesteuert werden, welches Zeichen zum Verbinden der Stringliste 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 Expansion nach dem Einlesen aller Variablen durchgeführt wird, spielt die Reihenfolge, in der sie definiert sind, keine Rolle.

Expandieren von Umgebungsvariablen

Beim Expandieren von Umgebungsvariablen verhält sich die Syntax ${variable} anders als $variable. Erstere expandiert den Inhalt der Variablen an der Stelle, die als Teil der Konfigurationsdatei geparst werden soll, während letztere den Inhalt einfach als Wert für die aktuelle Konfigurationsvariable zuweist. Dies hat Auswirkungen, wenn die Umgebungsvariable eine Liste von Elementen enthält, die durch Leerzeichen getrennt sind, oder eine andere von QDoc erkannte Formatierung.

Wenn zum Beispiel der Wert einer Umgebungsvariablen SRCDIRS "../src/a ../src/b" ist, dann

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

Konfigurationsvariablen

Variablenliste

• definiert
• hängt
• exampledirs
• Beispiele
• BeispieleInstallationspfad
• examples.fileextensions
• excludedirs
• ausgenommeneDateien
• extraBilder
• Unwahrheiten
• headerdirs
• Kopfzeilen
• headers.fileextensions
• HTML.footer
• HTML.postheader
• HTML.Stil
• Einbindungspfade
• Wörter ignorieren
• ignorieren, da
• Bilddateien
• Indizes
• Sprache
• Standortinfo
• Makro
• manifestmeta
• modulüberschrift
• Navigation
• outputdir
• ausgabeformate
• Ausgabepräfixe
• Ausgabesuffixe
• Projekt
• sourcedirs
• Quellen
• sources.fileextensions
• falsche
• tabsize
• url
• url.Beispiele
• version
• versionym
• warninglimit

Kategorien

• Allgemeine Konfigurationsvariablen
• Formatspezifische Konfigurationsvariablen

Beispiele für Konfigurationsdateien

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