Exemples de fichiers de manifeste

QDoc génère des fichiers example-manifest.xml contenant des informations sur tous les exemples documentés. Ces fichiers sont utilisés par Qt Creator pour afficher une liste d'exemples sur son écran d'accueil et pour créer des liens vers leur documentation.

Structure XML du manifeste

Un fichier manifeste présente la structure suivante :

<?xml version="1.0" encoding="UTF-8"?>
<instructionals module="QtGui">
    <examples>
        <example
            name="Analog Clock Window"
            docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
            projectPath="gui/analogclock/analogclock.pro"
            imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window.png">
            <description><![CDATA[The Analog Clock Window example shows how
                to draw the contents of a custom window.]]></description>
            <tags>analog,clock,window</tags>
            <fileToOpen>gui/analogclock/main.cpp</fileToOpen>
        </example>
        ...
    </examples>
</instructionals>

Chaque élément « <example> » contient des informations concernant le nom, la description, l'emplacement du fichier de projet et de la documentation, ainsi qu'une liste des balises associées à l'exemple.

Contenu des métadonnées du manifeste

Il est possible d’enrichir les fichiers de manifeste avec du contenu méta supplémentaire, c’est-à-dire des attributs et des balises supplémentaires pour certains exemples, à l’aide de la commande de configuration manifestmeta.

L'un des cas d'utilisation du contenu méta consiste à mettre en avant un certain nombre d'exemples marquants. Un autre consiste à améliorer la fonctionnalité de recherche en ajoutant des mots-clés pertinents sous forme de balises pour une certaine catégorie d'exemples.

Les exemples auxquels s’applique le méta-contenu sont spécifiés à l’aide d’un ou plusieurs filtres. La correspondance entre les exemples et les filtres s’effectue sur la base des noms, chaque nom d’exemple étant préfixé par un nom de module suivi d’une barre oblique. La correspondance simple avec des caractères génériques est prise en charge ; en utilisant * à la fin, il est possible de faire correspondre plusieurs exemples à une seule chaîne de caractères.

Exemple :

manifestmeta.filters                = highlighted sql webkit global

manifestmeta.highlighted.names      = "QtGui/Analog Clock Window" \
                                      "QtWidgets/Analog Clock"
manifestmeta.highlighted.attributes = isHighlighted:true

manifestmeta.sql.names              = "QtSql/*"
manifestmeta.sql.tags               = database,sql

manifestmeta.webkit.names           = "QtWebKitExamples/*"
manifestmeta.webkit.tags            = webkit

manifestmeta.global.names           = *
manifestmeta.global.tags            = qt6

Ci-dessus, un attribut « isHighlighted » est ajouté à deux exemples. Si la valeur de l’attribut est omise, QDoc utilise par défaut la chaîne « true ». Des balises supplémentaires sont ajoutées aux exemples « Qt WebKit » et « Qt SQL », et une autre balise est appliquée à tous les exemples en utilisant simplement « * » comme chaîne de correspondance.