Fonctionnement de GTK-Doc ?
GTK-Doc fonctionne en utilisant la documentation de fonctions placées dans le code source sous la forme de blocs de commentaires avec un formatage spécifique ou la documentation ajoutée aux fichiers prototypes que GTK-Doc utilise (notez cependant que GTK-Doc ne documente que les fonctions déclarées dans des fichiers d'en-tête ; il ne fait rien pour les fonctions statiques).
GTK-Doc consiste en un certain nombre de scripts Perl, chacun réalisant une étape du processus.
Il y a 5 étapes principales :
-
Écriture de la documentation. L'auteur complète les fichiers sources avec la documentation pour chaque fonction, macro, union, etc. (dans le passé, l'information était saisie dans les fichiers prototypes générés mais ce n'est plus recommandé).
-
Collecte des informations sur le code. gtkdoc-scan analyse les fichiers d'en-tête du code à la recherche des déclarations de fonctions, de macros, d'énumérations, de structures et d'unions. Il crée le fichier <module>-decl-list.txt contenant une liste des déclarations en les plaçant dans des sections en accord avec le fichier d'en-tête d'où elles proviennent. Lors du premier lancement, ce fichier est copié dans <module>-sections.txt. L'auteur peut réorganiser les sections et l'ordre des déclarations dans celui-ci, pour obtenir l'ordre final souhaité. Le deuxième fichier généré est <module>-decl.txt. Ce fichier contient les déclarations complètes trouvées lors de l'analyse. Si, pour une raison quelconque, on souhaite voir apparaître dans la documentation des éléments qui n'ont pas été trouvé lors de l'analyse, ou dont la déclaration doit apparaître différemment, il est possible d'ajouter des entrées dans <module>-overrides.txt similaires à celle de <module>-decl.txt.
gtkdoc-scanobj peut aussi être utilisé pour interroger de manière dynamique une bibliothèque à propos de n'importe quelle sous-classe de GtkObject qu'elle exporte. Il enregistre les informations sur la position de chaque objet dans la hiérarchie de classe et sur tous les arguments et signaux GTK fournis.
gtkdoc-scanobj ne devrait plus être utilisé. Il était nécessaire par le passé lorsque GObject était encore GtkObject dans gtk+.
-
Generating the XML and HTML/PDF. gtkdoc-mkdb turns the template files into XML files in the xml/ subdirectory. If the source code contains documentation on functions, using the special comment blocks, it gets merged in here. If there are no tmpl files used it only reads docs from sources and introspection data.
gtkdoc-mkhtml turns the XML files into HTML files in the html/ subdirectory. Likewise gtkdoc-mkpdf turns the XML files into a PDF document called <package>.pdf.
Files in xml/ and html/ directories are always overwritten. One should never edit them directly.
-
Résolution des références croisées entre les documents. Après installation des fichiers HTML, gtkdoc-fixxref peut être exécuté pour résoudre toutes les références croisées entre les différents documents. Par exemple, la documentation de GTK+ contient beaucoup de références croisées vers des types documentés dans le manuel de GLib. Lors de la création de l'archive des sources pour la distribution, gtkdoc-rebase transforme tous les liens externes en liens Web. Lorsque vous installez la documentation distribuée (pré-générée), la même application va essayer de retransformer les liens en liens locaux (là où ces documentations sont installées).