Einrichten Ihres Projekts
Die nächsten Abschnitte beschreiben die notwendigen Schritte, um GTK-Doc in Ihr Projekt zu integrieren. Nehmen wir an, wir arbeiten an einem Projekt namens »meep«. Das Projekt enthält eine Bibliothek namens »libmeep« sowie eine Endbenutzer-Anwendung namens »meeper«. Weiterhin gehen wir davon aus, dass wir autoconf und automake verwenden. Zusätzlich beschreibt der Abschnitt Klartext-Makefiles oder andere Erstellungssysteme die Grundlagen für die Arbeit in einer anderen Erstellungsumgebung.

Einrichten des Grundgerüsts der Dokumentation
Erstellen Sie in dem Ordner der obersten Ebene des Projekts die Unterordner namens docs/reference. Auf diese Weise können Sie auch docs/help für die Endbenutzerdokumentation anlegen. Es ist empfehlenswert, einen weiteren Unterordner mit dem Namen des Dokumentationspakets anzulegen. Für Pakete, die nur eine einzige Bibliothek enthalten, ist dieser Schritt nicht notwendig.
Dies kann dann wie nachstehend angezeigt aussehen:

Beispiel für die Ordnerstruktur

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

Integration in autoconf
Sehr einfach! Fügen Sie eine Zeile zu Ihrem configure.ac-Skript hinzu.

Integration in autoconf

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

Dazu müssen alle Entwickler gtk-doc installiert haben. Wenn es für das Projekt vertretbar ist, einen optionalen Erstellungsschritt für die api-doc zu haben, so können Sie es wie im Folgenden lösen. Lassen Sie es so, wie es ist, weil gtkdocize nach GTK_DOC_CHECK am Anfang einer Zeile sucht.

Halten Sie gtk-doc optional

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

Das erste Argument wird zur Überprüfung von gtkdocversion während des configure-Durchlaufs benutzt. Das zweite, optionale Argument wird von gtkdocize verwendet. Das Makro GTK_DOC_CHECK fügt verschiedene Schalter für configure hinzu:
--with-html-dir=PATH : Pfad zur installierten Dokumentation
--enable-gtk-doc : gtk-doc zur Erstellung der Dokumentation verwenden [Vorgabe=no]
--enable-gtk-doc-html : Erstellung der Dokumentation im HTML-Format [Vorgabe=yes]
--enable-gtk-doc-pdf : Erstellung der Dokumentation im PDF-Format [Vorgabe=no]
GTK-Doc ist standardmäßig deaktiviert! Denken Sie daran, die Option '--enable-gtk-doc' beim nächsten Durchlauf von configure zu übergeben. Anderenfalls wird die vorher erstellte Dokumentation installiert. Dies ergibt für Benutzer durchaus Sinn, aber nicht für Entwickler.
Weiterhin ist es empfehlenswert, dass das configure.ac-Skript die folgende Zeile enthält. Dies erlaubt gtkdocize das automatische Kopieren der Makrodefinition für GTK_DOC_CHECK in Ihr Projekt.

Vorbereitung für gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Nachdem alle Änderungen auf configure.ac angewendet wurden, aktualisieren Sie die Datei configure. Dies geschieht durch erneutes Ausführen von autoreconf -i oder autogen.sh.

Integration in automake
Kopieren Sie zunächst die Datei Makefile.am aus dem Beispiel-Unterordner der gtkdoc-sources in den API-Dokumentationsordner Ihres Projekts ( ./docs/reference/<package>). Eine lokale Kopie sollte beispielsweise unter /usr/share/doc/gtk-doc-tools/examples/Makefile.am verfügbar sein. Falls Sie mehrere Dokumentationspakete haben, müssen Sie dies für jedes davon wiederholen.
Im nächsten Schritt bearbeiten Sie die Einstellungen in Makefile.am. Allen Einstellungen ist ein Kommentar vorangestellt, der den jeweiligen Zweck beschreibt. Die meisten Einstellungen sind zusätzliche Flags, die an verschiedene Werkzeuge übergeben werden. Jedes der Werkzeuge hat eine Variable der Form <WERKZEUGNAME>_OPTIONEN. Alle Werkzeuge unterstützen --help zur Auflistung der unterstützten Parameter.

Integration in autogen
Die meisten Projekte dürften über ein autogen.sh-Skript verfügen, welches die Build-Infrastruktur nach dem Auschecken aus einem Versionsverwaltungssystem wie CVS, SVN oder Git erzeugt. GTK-Doc liefert ein Werkzeug namens gtkdocize mit, das in einem solchen Skript verwendet werden kann. Es sollte vor autoheader, automake oder autoconf ausgeführt werden.

Ausführen von gtkdocize durch autogen.sh

gtkdocize || exit 1

Beim Ausführen von gtkdocize wird gtk-doc.make in die Wurzel Ihres Projekts oder in jeden anderen durch die Option --docdir festgelegten Ordner kopiert. Außerdem wird das configure-Skript daraufhin überprüft, ob GTK_DOC_CHECK enthalten ist. Dieses Makro kann verwendet werden, um weitere Parameter an gtkdocize zu übergeben.
In früherer Zeit erzeugte GTK-Doc die Vorlagendateien dort, wo die Entwickler die Dokumentation platzierten. Das stellte sich als nicht optimal heraus, beispielsweise um generierte Dateien unter Versionskontrolle zu haben. Seit einigen Versionen kann GTK-Doc auch sämtliche Informationen aus Quellcode-Kommentaren ermitteln. Seit GTK-Doc 1.9 sind diese Vorlagen nicht mehr notwendig. Wir ermutigen die Entwickler, die Dokumentation innerhalb des Codes zu halten. gtkdocize unterstützt nun die Option --flavour no-tmpl, wodurch ein Makefile gewählt wird, welches die Verwendung der Vorlagen komplett umgeht. Neben der Möglichkeit, diese Option direkt beim Befehlsaufruf zu übergeben, kann Sie auch zu einer Umgebungsvariable namens GTKDOCIZE_FLAGS hinzugefügt oder als zweiter Parameter im GTK_DOC_CHECK-Makro im Konfigurationsskript aufgeführt werden. Falls Sie niemals Dateien im Vorlagenordner manuell bearbeitet oder aus älteren GTK-Doc-Versionen importiert haben, sollten Sie den Ordner löschen, z.B. in der Versionsverwaltung.

Erstellung der Dokumentation
Nach den bisher absolvierten Schritten ist es Zeit für den Build-Vorgang. Zunächst muss autogen.sh erneut ausgeführt werden. Falls dieses Skript auch den configure-Aufruf enthält, sollten Sie die Option --enable-gtk-doc hinzufügen. Anderenfalls führen Sie danach configure manuell aus, ebenfalls mit dieser Option.
Der erste Durchlauf von make erstellt verschiedene zusätzliche Dateien in den Dokumentationsordnern. Die bedeutendsten davon sind: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt.

Erstellung der Dokumentation

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

Nun können Sie docs/reference/<package>/index.html in Ihrem Browser öffnen. Zugegeben, das Ergebnis ist noch ein wenig enttäuschend. Im nächsten Abschnitt zeigen wir Ihnen, wie Sie die Seiten mit Leben füllen können.

Integration in Versionsverwaltungssysteme
Als Faustregel gilt, dass alle von Ihnen bearbeiteten Dateien auch unter Versionsverwaltung stehen sollten. In typischen Projekten sind das folgende Dateien: <package>.types, <package>-docs.xml (früher .sgml), <package>-sections.txt, Makefile.am.
Dateien in den Ordnern xml/ und html/ sollten nicht unter Versionsverwaltung gestellt werden, ebenso keine der .stamp-Dateien.

Integration in Klartext-Makefiles oder andere Erstellungssysteme
Für den Fall, dass jemand nicht automake und damit gtk-doc.mak einsetzen will, muss man die gtkdoc-Werkzeuge in eigenen makefiles (oder andere Werkzeuge) in der richtigen Reihenfolge aufrufen.

Schritte zur Erstellung der Dokumentation

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

Man muss sich Makefile.am und gtk-doc.mak anschauen, um die zusätzlich notwendigen Optionen herauszusuchen.

Integration in CMake-Erstellungssysteme
GTK-Doc stellt nun ein GtkDocConfig.cmake-Modul (und das korrespondierende GtkDocConfigVersion.cmake-Modul) bereit. Dadurch steht Ihnen der Befehl gtk_doc_add_module zur Verfügung, den Sie in die Datei CMakeLists.txt integrieren können.
Das folgende Beispiel zeigt, wie dieser Befehl eingesetzt wird.

Beispiel zur Verwendung von GTK-Doc mit CMake

find_package(GtkDoc 1.25 REQUIRED)

# Create the doc-libmeep target.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Build doc-libmeep as part of the default target. Without this, you would
# have to explicitly run something like `make doc-libmeep` to build the docs.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})