Att ställa in ditt projekt
De följande avsnitten beskriver vilka steg du måste utföra för att integrera GTK-Doc i ditt projekt. Dessa avsnitt förutsätter att vi arbetar på ett projekt kallat ”meep”. Detta projekt innehåller ett bibliotek kallat ”libmeep” och ett slutanvändarprogram kallat ”meeper”. Vi förutsätter också att du kommer att använda autoconf och automake. Dessutom kommer avsnittet vanliga makefiler eller andra byggsystem att beskriva de grundläggande sakerna som behöver fungera i ett annat byggsystem.

Att ställa in en skelettstruktur för dokumentation
Under toppnivåkatalogen för ditt projekt, skapa mappar kallade docs/reference (på detta sättet kan du också ha docs/help för slutanvändardokumentation). Det rekommenderas att skapa en annan underkatalog med namnet på dokumentations-paketet. För paket med bara ett bibliotek är detta steg inte nödvändigt.
Detta kan se ut enligt nedan:

Exempel på katalogstruktur

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

Integrering med autoconf
Väldigt enkelt! Bara lägg till en rad till ditt configure.ac-skript.

Integrering med autoconf

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

Detta kommer att kräva att alla utvecklare har gtk-doc installerat. Om det är okej för ditt projekt att ha ett valfritt api-dokumentation bygge, kan du lösa det enligt nedan. Behåll det som det är eftersom gtkdocize letar efter GTK_DOC_CHECK i början på en rad.

Låt gtk-doc vara valfritt

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

Det första argumentet används för att leta efter gtkdoc-versionen under konfigurationen. Det andra, valfria, argumentet används av gtkdocize. Makrot GTK_DOC_CHECK lägger också till flera configure-flaggor:
--with-html-dir=SÖKVÄG : sökväg till installerad dokumentation
--enable-gtk-doc : använd gtk-doc för att bygga dokumentation [standardvärde=no]
--enable-gtk-doc-html : bygg dokumentation i html-format [standardvärde=yes]
--enable-gtk-doc-pdf : bygg dokumentation i pdf-format [standardvärde=no]
GTK-Doc är inaktiverat som standard! Kom ihåg att skicka flaggan ”--enable-gtk-doc” vid nästa körning av configure. Annars kommer förgenererad dokumentation att installeras (vilket är rimligt för användare men inte för utvecklare).
Vidare rekommenderas det att du har följande rad i ditt configure.ac-skript. Den låter gtkdocize automatiskt kopiera makrodefinitionen för GTK_DOC_CHECK till ditt projekt.

Förberedelse för gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Efter att alla ändringar i configure.ac är gjorda, uppdatera filen configure. Detta kan göras genom att köra om autoreconf -i eller autogen.sh.

Integrering med automake
Kopiera först Makefile.am från underkatalogen examples från gtkdoc-sources till ditt projekts API-dokumentationskatalog ( ./docs/reference/<paket>). En lokal kopia bör finnas tillgänglig under t.ex. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Om du har flera dok-paket, repetera detta för vart och ett.
Nästa steg är att redigera inställningarna inuti Makefile.am. Alla inställningarna har en kommentar ovanför som beskriver deras syfte. De flesta inställningarna är extraflaggor som skickas till respektive verktyg. Varje verktyg har en variabel på formen <VERKTYGSNAMN>_OPTIONS. Alla verktygen har stöd för --help för att lista de parametrar som stöds.

Integrering med autogen
De flesta projekt kommer att ha ett autogen.sh-skript för att ställa in infrastrukturen för bygget efter utcheckning från ett versionshanteringssystem (så som cvs/svn/git). GTK-Doc tillhandahåller ett verktyg som heter gtkdocize som kan användas i ett sådant skript. Det bör köras före autoheader, automake eller autoconf.

Köra gtkdocize från autogen.sh

gtkdocize || exit 1

När gtkdocize kör kopierar det gtk-doc.make till din projektrot (eller den katalog som anges med flaggan --docdir). Det kontrollerar också ditt configure-skript efter ett anrop till GTK_DOC_CHECK. Detta makro kan användas för att skicka extra parametrar till gtkdocize.
Historiskt genererade GTK-Doc mallfiler i vilka utvecklare skrev in dokumentationen. Detta visade sig inte vara så bra (t.ex. på grund av behovet att ha genererade filer under versionskontroll). Sedan GTK-Doc 1.9 kan verktygen hämta all information från källkodskommentarer och mallar kan därför undvikas. Vi rekommenderar att hålla dokumentationen i koden. gtkdocize har nu stöd för flaggan --flavour no-tmpl som väljer en makefil som hoppar över tmpl-användning helt. Förutom att lägga till flaggan direkt vid körning av kommandot, kan den också läggas till i en miljövariabel kallad GTKDOCIZE_FLAGS eller inställd som en andra parameter i makrot GTK_DOC_CHECK i configure-skriptet. Om du inte har ändrat någon fil i tmpl för hand och migrerar från äldre gtkdoc-versioner, ta bort katalogen (t.ex. från versionshanteringssystemet).

Att köra dokumentationsbygget
Efter de tidigare stegen är det dags att köra bygget. Först måste vi köra om autogen.sh. Om detta skript kör configure åt dig, kan du ge det flaggan --enable-gtk-doc. Annars kör manuellt configure med denna flagga efteråt.
Den första körningen av make genererar flera extra filer i doc-katalogerna. De viktiga är <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt.

Att köra dokumentationsbygget

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

Du kan nu peka din webbläsare till docs/reference/<paket>/index.html. Ja, den är fortfarande lite sorglig. Men häng kvar, i nästa kapitel kommer vi att berätta för dig hur du fyller sidorna med liv.

Integrering med versionshanteringssystem
Som en tumregel är det filerna du redigerar som bör versionshanteras. För typiska projekt är det följande filer: <paket>.types, <paket>-docs.xml (tidigare .sgml), <paket>-sections.txt, Makefile.am.
Filer i katalogerna xml/ och html/ bör inte versionshanteras. Detsamma gäller .stamp-filerna.

Integrering med vanliga makefiler eller andra byggsystem
I det fall man inte vill använda automake och därför inte heller gtk-doc.mak kommer man att behöva anropa gtkdoc-verktygen i rätt ordning i sina egna makefiler (eller andra byggverktyg).

Byggsteg för dokumentation

DOC_MODULE=meep
// källkod har ändrats
gtkdoc-scan --module=$(DOC_MODULE) <källkodskatalog>
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<källkodskatalog>
// xml-filer har ändrats
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

Man kommer att behöva titta i Makefile.am och gtk-doc.mak för att plocka ut de extra flaggor som behövs.

Integrering med CMake-byggsystem
GTK-Doc kommer nu att producera en GtkDocConfig.cmake-modul (och motsvarande GtkDocConfigVersion.cmake-modul). Detta tillhandahåller ett gtk_doc_add_module-kommando som du kan ställa in i din CMakeLists.txt-fil.
Det följande exemplet visar hur du använder detta kommando.

Exempel på användning av GTK-Doc från CMake

find_package(GtkDoc 1.25 REQUIRED)

# Skapa målet doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Bygg doc-libmeep som standardmålet. Utan detta måste du uttryckligen
# köra något i stil med `make doc-libmeep` för att bygga dokumentationen.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Installera dokumentationen. (Detta förutsätter att du använder CMake-modulen
# GNUInstallDirs för att ställa in variabeln CMAKE_INSTALL_DOCDIR korrekt).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})