Unterstützung abgeleiteter Projekte

Einige Konfigurationsvariablen ermöglichen es Ihnen, QDoc zur Unterstützung von Qt-basierten Projekten zu nutzen. Sie ermöglichen es Ihrem Projekt, Verweise auf die Online-Qt-Dokumentation zu enthalten, was bedeutet, dass QDoc ohne expliziten Verknüpfungsbefehl Verweise auf die Klassenreferenzdokumentation erstellen kann.

Beschreibung

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

Siehe auch „project“.

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` für die Definition der Projektabhängigkeiten. Da direkte Pfade angegeben werden, sind beim Aufruf von QDoc keine Befehlszeilenoptionen wie ` --indexdir ` erforderlich.

Es ist möglich, Abhängigkeiten mit beiden Variablen zu definieren. In der Qt-Dokumentation wird ausschließlich die Variable „ depends “ verwendet.

Siehe auch „depends“, „project “ und „url“.

vorläufig

Verwenden Sie die Variable „ preliminary “, um den Statusbeschreiber anzupassen, der Elementen mithilfe des \preliminary Befehl zugewiesene Statusbeschreibung anzupassen.

Standardmäßig kennzeichnet QDoc diese Elemente in der API-Referenz mit dem Deskriptor „ Preliminary “ und generiert eine Meldung

„Dieses <Elementtyp> befindet sich in der Entwicklung und kann sich noch ändern.“

im Dokumentationstext des Elements. QDoc ersetzt <Elementtyp> in der obigen Meldung durch den jeweiligen Typ (z. B. „Modul“, „Funktion“ oder „Klasse“).

Um einen benutzerdefinierten Statusdeskriptor zu verwenden, definieren Sie eine Variable vom Typ „ preliminary “:

preliminary = "Technology preview"

Um eine benutzerdefinierte Statusmeldung zu verwenden, definieren Sie zusätzlich eine Untervariable „ preliminary.description “:

preliminary = "Technology preview"
preliminary.description = "This \1 is in technology preview and is subject to change."

Wenn in der Beschreibung der Platzhalter „ \1 “ vorkommt, ersetzt QDoc diesen durch den Elementtyp.

Die Variable „ preliminary “ wurde in Qt 6.12 in QDoc eingeführt.

productname

Verwenden Sie die Variable „ productname “, wenn der Name des zu dokumentierenden Produkts vom Namen der Dokumentation abweicht project Dies ist besonders nützlich bei umfangreicheren Dokumentationssätzen, die aus mehreren Dokumentationsprojekten und/oder -modulen bestehen, da QDoc dadurch in bestimmten Kontexten – wie beispielsweise beim \since Befehl.

Beispielsweise definiert Qt „Qt“ als „ productname “, während jedes einzelne Modul seinen eigenen „ project “-Namen definiert. Dies ermöglicht es Autoren, die Kurzschreibweise für den \since Befehl verwenden.

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

Siehe auch \since.

Projekt

Die Variable „ project “ gibt den Namen des Projekts an, das mit der Datei „ .qdocconf “ verknüpft ist. Dies ist eine obligatorische Variable, die in allen Projekten gesetzt werden muss.

Der Name des Projekts wird zur Bildung eines Dateinamens für die zugehörige Indexdatei des Projekts verwendet.

project = QtCreator

Dadurch wird eine Indexdatei mit dem Namen „ qtcreator.index “ erstellt.

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

Siehe auch „depends“, „indexes“ und „description“.

projectroot

Die Variable „ projectroot “ legt das Projektstammverzeichnis für die Berechnung relativer Pfade in Warnungsprotokollen fest.

projectroot = /path/to/project/root

QDoc verwendet die folgende Prioritätsreihenfolge, um das Projektstammverzeichnis zu ermitteln:

1. QDOC_PROJECT_ROOT Umgebungsvariable
2. projectroot Konfigurationsvariable
3. Wenn keine der beiden gesetzt ist, werden absolute Pfade verwendet

Wenn ein Projektstammverzeichnis festgelegt ist, wandelt QDoc absolute Dateipfade in den Warnungsprotokolldateien in relative Pfade um. Dadurch sind die Protokolle in verschiedenen Build-Umgebungen portierbar.

Das Build-System von Qt setzt automatisch ` QDOC_PROJECT_ROOT`, sodass Sie ` projectroot ` in der Regel nicht manuell festlegen müssen.

Bei der eigenständigen Nutzung von QDoc ermöglicht die Einstellung von ` projectroot ` die Portabilität der Warnprotokolle:

projectroot = /home/user/myproject
logwarnings = true

Die Variable ` projectroot ` wurde in QDoc 6.11 eingeführt. Siehe auch ` logwarnings`.

url

Die Variable „ url “ enthält die Basis-URL für die Dokumentation des aktuellen Projekts.

Die URL wird in der generierten Indexdatei des Projekts gespeichert. Wenn wir den Index eigenständig verwenden, nutzt QDoc diese URL als Basis-URL beim Erstellen von Links zu Klassen, Funktionen und anderen im Index aufgeführten Elementen.

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

...

Dadurch wird sichergestellt, dass bei jeder Generierung von Verweisen auf Entitäten im Modul „ Qt Core “ durch QDoc die Basis-URL https://doc.qt.io/qt/ verwendet wird.

Siehe auch „depends“, „indexes “ und „url.examples“.

url.examples

Die Variable „ url.examples “ enthält die Basis-URL für die Beispiele, die zum aktuellen Projekt gehören.

Ist sie definiert, wird am Ende jeder Beispiel-Dokumentationsseite ein Link zum Beispielprojektverzeichnis generiert. Die Variable ` url.examples ` bezieht sich auf das Stammverzeichnis der zu diesem Projekt gehörenden Beispiele; es kann sich um einen Link zu einem Online-Repository (beginnend mit `http://` oder `https://`) oder zum lokalen Dateisystem (`file://`) handeln.

Ist url.examples nicht definiert, gibt QDoc stattdessen eine Liste der Beispieldateien und -bilder aus.

Beispielsweise bei folgenden Definitionen:

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

Dann gilt für den folgenden \example Befehl:

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

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

Wenn die URL nach dem Beispielpfad weitere Komponenten enthält (z. B. einen Abfrage-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

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

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

Siehe auch „url“, „examplesinstallpath“ und \example.

url.sources

Die Variable „ url.sources “ enthält die Basis-URL für den C++-Quellcode des aktuellen Projekts. Dabei handelt es sich um eine URL, über die die Quellen des Projekts in einem Repository, beispielsweise auf github.com, eingesehen werden können.

Aktivieren Sie die Quellcode-Links, indem Sie „ url.sources.enabled “ auf „ true “ setzen. Wenn diese Option aktiviert ist, generiert QDoc im Abschnitt „Detaillierte Beschreibung“ jedes dokumentierten C++-Elements einen Link zu dessen Deklaration in der Synopse (Signatur).

Legen Sie außerdem das Stammverzeichnis der Quelldateien mit „ url.sources.rootdir “ fest. Der generierte Link setzt sich aus der Basis-URL (url.sources) und dem Pfad der Quelldatei relativ zu url.sources.rootdir zusammen.

Enthält die URL nach dem Pfad weitere Komponenten (beispielsweise einen Query-String, der einen Zweig angibt), fungiert „ \1 “ als Platzhalter für den Pfad. Ebenso fungiert „ \2 “ als Platzhalter für die Zeilennummer.

url.sources.linktext legt den für den Benutzer sichtbaren Linktext für Quelllinks fest. Standardmäßig ist der Linktext eine leere Zeichenkette; verwenden Sie den CSS-Selektor a.srclink, um die Links in der HTML-Ausgabe zu gestalten.

Beispielsweise mit der folgenden Konfiguration in „ qtbase/src/gui/doc/qtgui.qdocconf “:

url.sources = "https://code.qt.io/cgit/qt/qtbase.git/tree/\1?h=$QT_VER#n\2"
url.sources.rootdir = ../../..    # root of the `qtbase` repository
url.sources.linktext = "(source)"
url.sources.enabled = true

generiert QDoc für jede dokumentierte C++-Entität Links zu code.qt.io, die speziell auf den mit der Umgebungsvariablen ` QT_VER ` definierten Zweig zugeschnitten sind.

Die Variable ` url.sources ` wurde mit Qt 6.10 in QDoc eingeführt.

usealttextastitle

In manchen Fällen ist es wünschenswert, für Bilder einen „Tooltip“ bereitzustellen, wenn diese in grafischen Browsern dargestellt werden. QDoc bietet hierfür eine Möglichkeit, bei der der als optionale Zeichenkette an den Befehl \image Befehls als optionaler String übergeben wird, auch als „title“-Attribut für das Bild verwendet wird. Aktivieren Sie dieses Verhalten, indem Sie diese Variable in Ihrer QDoc-Konfigurationsdatei auf „ usealttextastitle = true “ setzen.

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

So unterstützen Sie abgeleitete Projekte

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

Beispielsweise enthält „qtgui.qdocconf“ (die Konfigurationsdatei für Qt GUI) die folgenden Variablendefinitionen:

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

...

Der Name der Projektvariablen wird zur Bildung eines Dateinamens für die Indexdatei verwendet; in diesem Fall wird die Datei „ qtgui.index “ erstellt. Die URL wird in der Indexdatei gespeichert. Anschließend verwendet QDoc diese als Basis-URL beim Erstellen von Links zu Klassen, Funktionen und anderen im Index aufgeführten Elementen.

Siehe auch „depends“, „indexes“, „project“ und „url“.