Nastavení vašeho projektu
Následující oddíl popisuje kroky, které musíte provést, abyste integrovali GTK-Doc do svého projektu. Tento oddíl předpokládá, že pracujeme na projektu nazvaném „meep“. Tento projekt obsahuje knihovnu nazvanou „libmeep“ a aplikaci pro koncového uživatele nazvanou „meeper“. Rovněž předpokládá, že používáte autoconf a automake. V oddílu prosté soubory Makefile nebo jiné sestavovací systémy budou popsány základní požadavky pro fungování s jinými postupy sestavování.

Nastavení kostry dokumentace
Pod nejvyšší složkou projektu vytvořte složky nazvané docs/reference (takto můžete mít i docs/help s dokumentací pro koncového uživatele). Je doporučeno vytvořit další podsložku s názvem balíčku s dokumentací. Pro balíčky s jedinou knihovnou není tento krok nutný.
Ve výsledku to může vypadat nějak takto:

Příklad struktury složek

meep/
  docs/
    reference/
      libmeep/
      meeper/
  src/
    libmeep/
    meeper/

Integrace s autoconf
Velmi snadné! Stačí jen přidat jeden řádek do vašeho skriptu configure.ac.

Integrace s autoconf

# check for gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

Vyžaduje to, aby všichni vývojáři měli gtk-doc nainstalované. Jestli u vašeho projektu stačí mít sestavení dokumentaci k API jen volitelné, můžete to vyřešit podle vzoru níže. Použijte to přesně tak, jak je uvedeno, protože gtkdocize hledá GTK_DOC_CHECK na začátku řádku.

Ponechání gtk-doc jako volitelného

# check for gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])

První argument se používá ke kontrole gtkdocversion v průběhu konfigurace. Druhý, volitelný argument používá nástroj gtkdocize. Makro GTK_DOC_CHECK také přidává několik přepínačů pro configure:
--with-html-dir=CESTA: cesta, kam se má dokumentace nainstalovat
--enable-gtk-doc: použít k sestavení dokumentace gtk-doc [výchozí je ne]
--enable-gtk-doc-html: sestavit dokumentaci ve formátu HTML [výchozí je ano]
--enable-gtk-doc-pdf: sestavit dokumentaci ve formátu PDF [výchozí je ne]
GTK-Doc je standardně vypnuté! Nezapomeňte zadat přepínač „--enable-gtk-doc“ při dalším spuštění configure. Jinak se nainstaluje předgenerovaná dokumentace (která může mít význam pro uživatele, ale ne pro vývojáře).
Mimo to je ještě doporučeno, abyste měli ve skriptu configure.ac následující řádek. Umožní to gtkdocize automaticky nakopírovat definice maker pro GTK_DOC_CHECK do vašeho projektu.

Příprava pro gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Po provedení změn v configure.ac aktualizujte soubor configure. To se dá udělat opětovným spuštěním autoreconf -i nebo autogen.sh.

Integrace s automake
Jako první nakopírujte Makefile.am z podsložky examples ve složce gtkdoc-sources do složky s dokumentací API svého projektu (./docs/reference/<package>). Místní kopie by měla být k dispozici např. pod /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Pokud máte více balíčků s dokumentací, opakujte tento krok pro každý z nich.
Dalším krokem je úprava nastavení v Makefile.am. Všechna nastavení mají komentáře s popisem jejich účelu. Většina nastavení má doplňující příznaky předávané do dotyčných nástrojů. Každý nástroj má proměnnou ve formátu <NÁZEVNÁSTROJE>_OPTIONS. Všechny nástroje podporují --help pro vypsání podporovaných přepínačů.

Integrace s autogen
Většina projektů má skript autogen.sh, který po stažení ze systému pro správu verzí (jako je CVS, SVN nebo Git), nastaví infrastrukturu pro sestavení. GTK-Doc se dodává s nástrojem nazvaným gtkdocize, který lze v takovémto skriptu využít. Měl by být spuštěný před autoheader, automake nebo autoconf.

Spuštění gtkdocize z autogen.sh

gtkdocize || exit 1

Když spustíte gtkdocize, tak nakopíruje do kořenové složky vašeho projektu (nebo složky určené přepínačem --docdir) soubor gtk-doc.make. Navíc zkontroluje váš skript configure, jestli volá GTK_DOC_CHECK. Toto makro můžete použít k předání dalších parametrů do gtkdocize.
Dříve GTK-Doc generovalo soubory šablon, do kterých vývojáři vkládali dokumentaci. To bylo zrušeno, protože to nebylo příliš dobré (například kvůli potřebě mít generované soubory pod správou verzí). Od GTK-Doc verz 1.9 umí nástroje získávat všechny informace z komentářů ve zdrojových kódech a šablony tak můžete úplně vynechat. Doporučujeme lidem, aby dokumentaci udržovali v rámci kódu. gtkdocize nyní podporuje přepínač --flavour=no-tmpl, který způsobí, že makefile použití tmpl úplně vynechá. Mimo přidání této volby přímo do volaného příkazu, jej můžete předat také jako proměnnou prostředí s názvem GTKDOCIZE_FLAGS, nebo nastavit jako druhý parametr v makru GTK_DOC_CHECK v konfiguračním skriptu. Pokud jste nikdy ručně neměnili žádný soubor v tmpl a přecházíte ze starší verze gtkdoc, tak tuto složku prosím odstraňte (například ze správy verzí).

Sestavení dokumentace
Po dokončení předchozích kroků nastal čas spustit sestavení. Nejdříve musíte znovu spustit autogen.sh. Pokud tento skript pro vás provádí nastavení, předejte mu přepínač --enable-gtk-doc. Jinak potom ručně spusťte configure s tímto přepínačem.
První make spustí vygenerování několika doplňujících souborů ve složkách doc. Podstatné jsou tyto: <package>.types, <package>-docs.xml (dříve .sgml) a <package>-sections.txt.

Sestavení dokumentace

./autogen.sh --enable-gtk-doc
make

Nyní se můžete ve svém prohlížeči podívat na docs/reference/<package>/index.html. Zatím je to poněkud neuspokojivé, že? Ale nebojte, v následující kapitole vám řekneme, jak stránky uvést do života.

Integrace se systémem pro správu verzí
Podle nepsaných pravidel byste soubory, které upravujete, měli udržovat ve správě verzí. U typických projektů to jsou tyto soubory: <balíček>.types, <balíček>-docs.xml (dříve .sgml), <balíček>-sections.txt a Makefile.am.
Soubory ze složek xml/ a html/ by neměly být zařazeny do správy verzí. A ani žádné soubory .stamp.

Integrace s prostými soubory Makefile nebo jinými sestavovacími systémy
Když někdo nechce používat automake, a tím pádem gtk-doc.mak, bude muset volat nástroje gtkdoc ve správném pořadí ve vlastních souborech make (nebo jiných nástrojích).

Kroky sestavení dokumentace

DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) <zdrojová-složka>
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<zdrojová-složka>
// xml files have changed
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

Na výběr dalších potřebných voleb se musíte se podívat do Makefile.am a gtk-doc.mak.

Integrace se sestavovacím systémem CMake
GTK-Doc nyní nabízí modul GtkDocConfig.cmake (a příslušný modul GtkDocConfigVersion.cmake). Ten poskytuje příkaz gtk_doc_add_module, který můžete nastavit ve svém souboru CMakeLists.txt.
Následující příklad ukazuje, jak tento příkaz použít:

Příklad použití GTK-Doc z CMake

find_package(GtkDoc 1.25 REQUIRED)

# Vytvoření cíle doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Sestavení doc-libmeep jako součásti výchozího cíle. Bez tohoto byste museli
# ručně spouštět něco jako `make doc-libmeep`, aby se dokumentace sestavila.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Instalace dokumentace. (Předpokládá to, že používáte modul CMake GNUInstallDirs
# ke správnému nastavení proměnné CMAKE_INSTALL_DOCDIR).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})