Exemples de fichiers de manifeste

QDoc génère des fichiers example-manifest.xml qui contiennent des informations sur tous les exemples documentés. Ces fichiers sont utilisés par Qt Creator pour présenter une liste d'exemples dans son écran de bienvenue et pour créer un lien vers leur documentation.

Structure XML du manifeste

Un fichier manifeste a 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 sur le nom, la description, l'emplacement du fichier de projet et de la documentation, ainsi qu'une liste de balises associées à l'exemple.

Contenu méta du manifeste

Il est possible d'ajouter du méta-contenu aux fichiers manifestes, c'est-à-dire des attributs et des balises supplémentaires pour les exemples sélectionnés, à l'aide de la commande de configuration manifestmeta.

Un des cas d'utilisation du méta-contenu est la mise en évidence d'un certain nombre d'exemples importants. Un autre est d'améliorer la fonctionnalité de recherche en ajoutant des mots-clés pertinents en tant que 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 se fait sur la base des noms, chaque nom d'exemple étant précédé d'un nom de module et d'une barre oblique. Une simple correspondance avec un joker est possible ; en utilisant * à la fin, il est possible de faire correspondre plusieurs exemples avec une seule chaîne.

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 la chaîne true par défaut. Des balises supplémentaires sont ajoutées pour les exemples Qt WebKit et Qt SQL, et une autre balise est appliquée à tous les exemples en utilisant uniquement * comme chaîne de correspondance.