Jak GTK-Doc pracuje?

GTK-Doc pracuje na základě dokumentace funkcí umístěné přímo v souborech se zdrojovým kódem ve speciálně formátovaných komentářových blocích, nebo dokumentace přidané do souborů šablon, které GTK-Doc používá (ačkoliv je nutno poznamenat, že GTK-Doc dokumentuje pouze funkce, které jsou deklarované v hlavičkových souborech; pro statické funkce žádný výstup nevytváří).

GTK-Doc sestává z řady perlových skriptů, z nichž každý provádí jinou část procesu.

Celý proces se skládá z pěti hlavních kroků:

  1. Psaní dokumentace. Autor doplní soubory se zdrojovým kódem dokumentací pro každou funkci, makro, strukturu atd. (Dříve se informace vkládaly do souborů s vygenerovanými šablonami, což se již nedoporučuje).

  2. Shromáždění informací o kódu. gtkdoc-scan projde hlavičkové soubory kódu a vyhledá při tom deklarace funkcí, maker, výčtů, struktur a sjednocení. Tím se vytvoří soubor <module>-decl-list.txt obsahující seznam deklarací, které jsou rozdělené do oddílů podle hlavičkového souboru, ze kterého pochází. Při prvním spuštění se tento soubor zkopíruje do <module>-sections.txt. Autor může změnit uspořádání oddílů a jejich pořadí v rámci deklarací tak, jak to požaduje ve výsledku. Druhý soubor, který se vytvoří, je <module>-decl.txt. Tento soubor obsahuje úplné deklarace nalezené při procházení. Pokud byste z nějakého důvodu chtěli v dokumentaci zahrnout symbol, který při procházení nebyl nalezen, nebo jeho deklarace vypadá jinak, můžete jej umístit podobně jako v <module>-decl.txt do <module>-overrides.txt.

    Dá se také použít gtkdoc-scanobj k dynamickým dotazům do knihoven na podtřídy objektu GObject, které exportují. Tím se uloží informace o pozici každého objektu v hierarchii tříd a o argumentech a signálech objektu GObject, které poskytují.

    gtkdoc-scanobj by se ale již používat nemělo. Bylo zapotřebí v minulosti, kdy byl GObject ještě GtkObject v rámci gtk+.

  3. Generování XML a HTML/PDF. gtkdoc-mkdb přemění soubory šablon na soubory XML v podsložce xml/. Pokud zdrojový kód obsahuje dokumentaci funkcí za použití speciálních komentářových bloků, tak zde se sloučí. V případě, že není použitý žádný soubor šablon, načte se dokumentace pouze ze zdrojového kódu a introspektivních dat.

    gtkdoc-mkhtml převádí soubory XML na soubory HTML v podsložce html/. Obdobně gtkdoc-mkpdf převádí soubory XML na dokument PDF nazvaný <balíček>.pdf.

    Soubory ve složkách xml/ a html/ jsou vždy přepsány. Nikdy by neměly být upravovány přímo.

  4. Opravy křížových odkazů mezi dokumenty. Po nainstalování souborů HTML můžete spustit gtkdoc-fixxref, aby se opravily křížové odkazy mezi samostanými dokumenty. Například dokumentace GTK+ obsahuje křížové odkazy na typy zdokumentované v příručce GLib. Když vytváříte zdrojový balíček pro distribuci, gtkdoc-rebase předělá všechny externí odkazy na webové odkazy. Když se distribuovaná (předgenerovaná) dokumentace instaluje, pokusí se tatáž aplikace předělat odkazy zpátky na místní odkazy (na dokumenty, které jsou nainstalované).