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.
-
Génération des fichiers « prototypes ». gtkdoc-mktmpl crée un certain nombre de fichiers dans le sous-répertoire tmpl/, en utilisant les informations récoltées lors de la première étape (notez que le script peut être exécuté plusieurs fois, il est fait en sorte qu'aucune donnée ne soit jamais perdue).
Depuis GTK-Doc 1.9, les prototypes peuvent être évités. Nous encourageons tout le monde à conserver la documentation dans le code. gtkdocize prend maintenant en charge l'option --flavour no-tmpl qui choisit un makefile qui évite complètement l'utilisation de tmpl. Si vous n'avez jamais modifié de fichiers à la main dans tmpl, effacez le répertoire (par ex. à partir d'un système de gestion de versions).
-
Génération du SGML/XML et du HTML/PDF. gtkdoc-mkdb transforme les fichiers prototypes en fichiers SGML ou XML dans le répertoire sgml/ ou xml/. Si le code source contient de la documentation sur les fonctions, en utilisant les blocs de commentaires spéciaux, elle sera fusionnée ici. Si aucun fichier tmpl n'est utilisé, seule la documentation contenue dans les sources et les données d'introspection seront lues. Nous recommandons l'utilisation de XML DocBook.
gtkdoc-mkhtml transforme les fichiers SGML/XML en fichiers HTML dans le répertoire html/. De même gtkdoc-mkpdf transforme les fichiers SGML/XML en documents PDF appelés <package>.pdf.
Les fichiers dans les répertoires sgml/ ou xml/ et html/ sont toujours écrasés. Il ne faut pas les modifier directement.
-
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).