Configurando su proyecto
Las siguientes secciones describen los pasos que realizar para integrar GTK-Doc en su proyecto. Estas secciones asumen que se trabaja en un proyecto llamado «meep». Este proyecto contiene una biblioteca llamada «libmeep» y una aplicación final de usuario llamada «meeper». También se asume que usará «autoconf» y «automake». En la sección Integración con makefiles u otros sistemas de construcción se describen las necesidades básicas para trabajar con un sistema de construcción diferente.

Configurar el esquema de la documentación
Bajo su carpeta de nivel superior cree carpetas llamadas docs/reference (de esta forma también puede tener docs/help para la documentación final de usuario). Se recomienda crear otra subcarpeta con el nombre doc-package. Para paquetes con una sola biblioteca este paso no es necesario.
Esto después aparecerá como se muestra debajo:

Ejemplo de estructura de carpetas

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

Integración con autoconf
Muy fácil, simplemente añada una línea a su script configure.ac.

Integración con autoconf

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

Esto requerirá que todos los desarrolladores tengan gtk-doc instalado. Si para su proyecto es correcto tener una configuración de construcción de api-doc opcional, puede resolver esto como sigue. Manténgalo como está, ya que gtkdocize busca en GTK_DOC_CHECK al inicio de la línea.

Mantener gtk-doc como opcional

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

El primer argumento se usa para comprobar gtkdocversion durante la configuración. El segundo, y opcional, argumento lo usa gtkdocize. La macro GTK_DOC_CHECK también añade diversas opciones de configuración:
--with-html-dir=RUTA: ruta a los documentos instalados
--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]
--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=sí]
--enable-gtk-doc: usar gtk-doc para construir la documentación [predeterminado=no]
GTK-Doc está desactivado de forma predeterminada. Recuerde pasar la opción «--enable-gtk-doc» en la siguiente ejecución de configure. De otra forma, la documentación pregenerada se instala (lo que tiene sentido para usuarios, pero no para desarrolladores).
Aún más, se recomienda que tenga la siguiente línea en su script configure.ac. Esto permite que gtkdocize copie automáticamente la definición de la macro para GTK_DOC_CHECK a su proyecto.

Preparación para gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Después de hacer los cambios en el configure.ac actualice el archivo configure. Esto se puede hacer volviendo a ejecutar autoreconf -i o autogen.sh.

Integración con automake
Primero copie el archivo Makefile.am de la subcarpeta examples de gtkdoc-sources a la carpeta de documentación de la API de su proyecto (./docs/reference/<package>). Debería haber una copia local disponible en /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Si tiene varios paquetes de documentación, repítalo para cada uno de ellos.
El siguiente paso es editar la configuración dentro de Makefile.am. Todos los ajustes tienen un comentario encima que describe su propósito. Muchos ajustes son opciones adicionales pasadas a las respectivas herramientas. Cada herramienta tiene una variable de la forma <NOMBRE_DE_LA_HERRAMIENTA>_OPCIONES. Todas las herramientas soportan --help para listar los parámetros que soportan.

Integración con autogen
La mayoría de los proyectos tienen un script autogen.sh para configurar la infraestructura de construcción después de hacer un «checkout» desde los sistemas de control de versiones (tales como cvs/svn/git). GTK-Doc tiene una herramienta llamada gtkdocize que se puede usar en tal script. Se debería ejecutar antes que autoheader, automake o autoconf.

Ejecutar gtkdocize desde autogen.sh

gtkdocize || exit 1

Al ejecutar gtkdocize copia gtk-doc.make a la raíz de su proyecto (o cualquier carpeta especificada por la opción --docdir). También comprueba su script de configuración para la invocación de GTK_DOC_CHECK. Esta macro se puede usar para pasar parámetros adicionales a gtkdocize.
Históricamente GTK-Doc generaba plantillas de archivos donde los desarrolladores introducían los documentos. Al final esto resulto no ser muy bueno (por ejemplo, por la necesidad de tener archivos generados bajo un control de versiones). Desde la versión de DTK-Doc 1.9 las herramientas pueden obtener toda la información desde los comentarios del código fuente y por ello se pueden evitar las plantillas. Se anima a los desarrolladores a mantener su documentación en el código. gtkdocize ahora soporta una opción --flavour no-tmpl que elije un makefile que omite completamente el uso de plantillas. Además de añadir la opción directamente a la línea de comandos al invocarlo, se pueden añadir a una variable de entorno llamada GTKDOCIZE_FLAGS o configurar como un segundo parámetro en la macro GTK_DOC_CHECK en el script de configuración. Si nunca ha cambiado un archivo tmpl (plantilla) a mano, elimine la carpeta una vez (ej. desde el sistema de control de versiones).

Ejecutar la construcción de la documentación
Después de los pasos anteriores es hora de ejecutar el constructor. Primero se debe volver a ejecutar autogen.sh. Si este script ejecuta configure automáticamente, entonces debe pasar la opción --enable-gtk-doc. De otra forma, ejecute posteriormente configure con esta opción.
El primer make genera diversas líneas adicionales en las carpetas de documentación. Las importantes son: <paquete>.types, <paquete>-docs.xml (.sgml en el pasado), <paquete>-sections.txt.

Ejecutar la construcción de la documentación

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

Ahora puede apuntar su navegador a docs/reference/<paquete>/index.html. Sí, aún es un poco decepcionante. Pero espere, durante el siguiente capítulo aprenderá a rellenar las páginas con información.

Integración con los sistemas de control de versiones
Como regla principal, son los archivos que edita los que deberían estar bajo el control de versiones. Para proyectos típicos son los archivos: <paquete>.types, <paquete>-docs.xml (anteriormente .sgml), <paquete>-sections.txt, Makefile.am.
Los archivos de las carpetas xml/ y html/ No deberían estar bajo control de versiones. Tampoco ninguno de los archivos .stamp.

Integración con makefiles u otros sistemas de construcción
En el caso de que no quiera usar automake y por ello gtk-doc.mak deberá llamar a las herramientas gtkdoc en el orden correcto en makefiles propios (o en otras herramientas de construcción).

Pasos de construcción de la documentación

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

Deberá mirar en el archivo Makefile.am y gtk-doc.mak para elegir las opciones adicionales necesarias.

Integración con sistemas de construcción CMake
Ahroa, GTK-Doc proporciona un módulo GtkDocConfig.cmake (y el correspondiente módulo GtkDocConfigVersion.cmake). Esto proporciona un comando gtk_doc_add_module que puede configurar en su archivo CMakeLists.txt.
El siguiente ejemplo muestra cómo usar este comando.

Ejeplo de uso de GTK-Doc desde 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})