Unterstützende abgeleitete Projekte

Einige Konfigurationsvariablen erlauben es Ihnen, QDoc zur Unterstützung von Qt-basierten Projekten zu verwenden. Sie erlauben es Ihrem Projekt, Links zur Online-Qt-Dokumentation zu enthalten, was bedeutet, dass QDoc in der Lage sein wird, Links zur Klassenreferenzdokumentation zu erstellen, ohne dass ein expliziter Link-Befehl erforderlich ist.

Beschreibung

Die Variable description enthält eine kurze Beschreibung des zugehörigen Projekts.

Siehe auch Projekt.

Indizes

Die Variable indexes definiert eine Reihe von Pfaden zu den zu ladenden Indexdateien.

indexes = \
    $QT_INSTALL_DOCS/qtcore/qtcore.index \
    $SOME_OTHER_PROJECT/doc/foo.index

Die Variable indexes bietet eine Alternative zu depends, um die Abhängigkeiten des Projekts zu definieren. Da direkte Pfade angegeben werden, ist beim Aufruf von QDoc keine -indexdir Kommandozeilenoption(en) erforderlich.

Es ist möglich, Abhängigkeiten mit beiden Variablen zu definieren. Die Qt-Dokumentation verwendet nur die Variable depends.

Siehe auch depends, project und url.

Produktname

Verwenden Sie die Variable productname, wenn der Name des zu dokumentierenden Produkts nicht mit dem Namen der Dokumentation übereinstimmt. project Dies ist besonders nützlich für größere Dokumentationsmengen, die aus mehreren Dokumentationsprojekten und/oder Modulen bestehen, da es QDoc erlaubt, den Produktnamen anstelle des Projektnamens in bestimmten Kontexten zu generieren, wie z.B. dem \since Befehl.

Qt definiert zum Beispiel Qt als productname, während jedes einzelne Modul seinen eigenen project Namen definiert. Dies erlaubt es den Autoren, die Kurzschreibweise für den \since Befehl zu verwenden.

Diese Konfigurationsvariable wurde in QDoc mit Qt 6.9 eingeführt.

Siehe auch \since.

Projekt

Die Variable project gibt einen Namen für das Projekt an, das mit der Datei .qdocconf verbunden ist. Dies ist eine obligatorische Variable, die in allen Projekten gesetzt werden muss.

Der Projektname wird verwendet, um einen Dateinamen für die Indexdatei des zugehörigen Projekts zu bilden.

project = QtCreator

Dies führt dazu, dass eine Indexdatei mit dem Namen qtcreator.index erstellt wird.

Enthält der Projektname Leer- oder Sonderzeichen, werden diese im generierten Indexdateinamen durch Bindestriche ('-') ersetzt.

Siehe auch Abhängigkeiten, Indizes und Beschreibung.

url

Die Variable url enthält die Basis-URL für die mit dem aktuellen Projekt verbundene Dokumentation.

Die URL wird in der generierten Indexdatei für das Projekt gespeichert. Wenn wir den Index alleine verwenden, wird QDoc diese als Basis-URL verwenden, wenn es Links zu Klassen, Funktionen und anderen im Index aufgeführten Dingen erstellt.

project     = QtCore
description = Qt Core Reference Documentation
url         = https://doc.qt.io/qt/

...

Dadurch wird sichergestellt, dass immer dann, wenn QDoc Verweise auf Entitäten im Modul Qt Core erzeugt, die Basis-URL https://doc.qt.io/qt/ lautet.

Siehe auch depends, indexes und url.examples.

url.examples

Die Variable url.examples enthält die Basis-URL für die mit dem aktuellen Projekt verbundenen Beispiele.

Falls definiert, wird am Ende jeder Beispiel-Dokumentationsseite ein Link zum Verzeichnis des Beispielprojekts generiert. Die Variable url.examples verweist auf das Stammverzeichnis der Beispiele, die zu diesem Projekt gehören; es kann ein Link zu einem Online-Repository (beginnend mit http:// oder https://) oder zum lokalen Dateisystem (file://) sein.

Wenn url.examples nicht definiert ist, wird QDoc stattdessen eine Liste der Beispieldateien und Bilder ausgeben.

Zum Beispiel, wenn diese Definitionen gegeben sind:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/"
examplesinstallpath = corelib

Dann wird für den folgenden \example-Befehl

/*!
    \example threads/semaphores
    ...
*/

QDoc erzeugt einen Link zu https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores.

Enthält die URL nach dem Beispielpfad weitere Komponenten (z. B. einen Query-String), kann \1 als Platzhalter für den Pfad verwendet werden:

url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER"
examplesinstallpath = corelib

Mit demselben \example-Befehl wie oben und unter der Annahme, dass $QT_VER zu 5.13 expandiert, lautet die generierte URL https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13.

url.examples Die Variable \1 wurde in QDoc Version 5.13 eingeführt.

Siehe auch url, examplesinstallpath, und \example.

usealttextastitle

In manchen Fällen ist es wünschenswert, einen "Tooltip" für Bilder bereitzustellen, wenn diese in grafischen Browsern dargestellt werden. QDoc bietet eine Möglichkeit dies zu tun, bei der der Alttext, der als optionaler String an den \image Befehl angegeben wird, auch als Titelattribut für das Bild verwendet wird. Aktivieren Sie dieses Verhalten, indem Sie die Variable this mit usealttextastitle = true in Ihrer QDoc-Konfigurationsdatei setzen.

Diese Konfigurationsvariable wurde in QDoc mit Qt 6.9 eingeführt.

Wie man abgeleitete Projekte unterstützt

Diese Funktion nutzt die umfassenden Indizes, die von QDoc bei der Erstellung der Qt-Referenzdokumentation erzeugt werden.

Zum Beispiel enthält qtgui.qdocconf (die Konfigurationsdatei für Qt GUI) die folgenden Variablendefinitionen:

project     = QtGui
description = Qt GUI Reference Documentation
url         = http://doc.qt.io/qt/

...

Die Projektvariable name wird verwendet, um einen Dateinamen für die Indexdatei zu bilden; in diesem Fall wird die Datei qtgui.index erstellt. Die Url wird in der Indexdatei gespeichert. Danach wird QDoc diese als Basis-URL verwenden, wenn es Links zu Klassen, Funktionen und anderen im Index aufgeführten Dingen erstellt.

Siehe auch depends, indexes, project, und url.