Preparando seu projeto
As próximas seções descrevem quais as etapas para realizar a integração do GTK-Doc em seu projeto. Estas seções consideram que nós trabalhamos em um projeto chamado “meep”. Este projeto contém uma biblioteca chamada “libmeep” e um aplicativo para usuário final chamado “meeper”. Nós também consideramos que você estará usando autoconf e automake. Além disso, a seção sobre makefiles simples ou outros sistemas de compilação vai descrever as necessidades básicas para trabalhar em uma configuração de compilação diferente.

Preparando o esqueleto de uma documentação
No diretório raiz do seu projeto, crie pastas chamadas docs/reference (desta forma, você também pode ter docs/help para documentação para usuário final). É recomendado criar um outro subdiretório com o nome do pacote de documentação. Para pacotes com apenas uma biblioteca, esta etapa não é obrigatória.
Isto pode, então, parecer como exibido abaixo:

Exemplo de estrutura de diretórios

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

Integração com autoconf
Muito fácil! Basta adicionar uma linha ao seu script configure.ac.

Integração com autoconf

# verifica por gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

Isso vai exigir que todos os desenvolvedores tenham o gtk-doc instalado. Se não houver problema para seu projeto ter uma configuração opcional de compilação de documentação de API, você pode resolver isso como mostrado abaixo. Mantenha assim, pois o gtkdocize está procurando por GTK_DOC_CHECK no começo de uma linha.

Mantenha o gtk-doc como opcional

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

O primeiro argumento é usado para verificar a gtkdocversion em tempo de compilação. O segundo argumento é opcional, sendo usado por gtkdocize. A macro GTK_DOC_CHECK também adiciona várias opções de configuração:
--with-html-dir=CAMINHO : caminho para as documentações instaladas
--enable-gtk-doc : usa gtk-doc para compilar documentação [padrão=no]
--enable-gtk-doc-html : compila documentação em formato html [padrão=sim]
--enable-gtk-doc-pdf : compila documentação em formato pdf [padrão=não]
GTK-Doc está desabilitado por padrão! Lembre-se de passar a opção "--enable-gtk-doc" à próxima execução do configure. Do contrário, uma documentação gerada previamente é instalada (o que faz sentido para usuários, mas não para desenvolvedores).
Além disso, é recomendado que você tenha a seguinte linha dentro do seu script configure.ac. Ela permite que gtkdocize copie automaticamente a definição de macro para GTK_DOC_CHECK para o seu projeto.

Preparação para gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Após todas as alterações do configure.ac serem feitas, atualize o arquivo configure. Isso pode ser feito executando novamente autoreconf -i ou autogen.sh.

Integração com automake
Primeiro copie o Makefile.am dos subdiretório do exemplo do gtkdoc-sources para o diretório de documentação da API do seu projeto ( ./docs/reference/<pacote>). Uma cópia local deveria estar disponível sob, por exemplo, /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Se você tiver múltiplos pacotes de documentação, repita isso para cada um.
A próxima etapa é editar as configurações dentro do Makefile.am. Todas as configurações tem um comentário em cima que descreve seu propósito. A maioria das configurações são opções extras passadas para as respectivas ferramentas. Cada ferramenta tem uma variável na forma <NOME-FERRAMENTA>_OPTIONS. Todas as ferramentas têm suporte a --help pra listar os parâmetros disponíveis.

Integração com autogen
A maioria dos projetos têm um script autogen.sh para configurar a infraestrutura de compilação após baixar do sistema de controle de versão (como cvs/svn/git). GTK-Doc vêm com uma ferramenta chamada gtkdocize que pode ser usada em um script assim. O gtkdocize deveria ser executado antes de autoheader, automake ou autoconf.

Executando gtkdocize no autogen.sh

gtkdocize || exit 1

Ao executar gtkdocize, ele copia gtk-doc.make para a raiz do seu projeto (ou qualquer diretório especificado pela opção --docdir). Ele também verifica se seu script de configuração pela chamada de GTK_DOC_CHECK. Esta macro pode ser usada para passar parâmetros extras para gtkdocize.
Historicamente, GTK-Doc estava gerando arquivos modelo (template) nos quais os desenvolvedores inseriam as documentações. Isso acabou sendo não tão bom (ex.: a necessidade de serem gerados arquivos sob controle de versão). Desde o GTK-Doc 1.9 as ferramentas podem obter todas as informações dos comentários no fonte e, portanto, os arquivos modelo podem ser evitados. Nós encorajamos as pessoas a manter a documentação no código. O gtkdocize possui agora suporte à opção --flavour no-tmpl que escolhe um makefile que ignora totalmente o uso de tmpl. Além de adicionar a opção diretamente à chamada do comando, elas também podem ser adicionadas a uma variável de ambiente chamada GTKDOCIZE_FLAGS ou definidas como um segundo parâmetro na macro GTK_DOC_CHECK no script configure. Se você nunca alterou um arquivo tmpl a mão e está migrando de versões antigas do gtkdoc, por favor remova o diretório (ex.: do sistema de controle de versão).

Executando a compilação da documentação
Após as etapas anteriores, é hora de executar a compilação. Primeiro, nós queremos executar novamente o autogen.sh. Se este script executa o configure para você, então forneça a este a opção --enable-gtk-doc. Do contrário, execute manualmente configure com esta opção em seguida.
A primeira execução do make cria vários arquivos adicionais nos diretórios de documentação. Os importantes são: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt.

Executando a compilação da documentação

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

Agora você pode apontar seu navegador para docs/reference/<pacote>/index.html. Sim, é um pouco desapontador. Mas aguente aí, durante o próximo capítulo nós vamos dizer como você pode preencher as páginas com vida.

Integração com sistemas de controle de versão
Como uma regra de ouro, são aqueles arquivos que você edita que deveriam entrar no controle de versão. Para projetos normais, esses são os arquivos: <pacote>.types, <pacote>-docs.xml (no passado, .sgml), <pacote>-sections.txt, Makefile.am.
Arquivos nos diretórios xml/ e html/ não deveriam entrar no controle de versão. Da mesma forma, não deveriam entrar arquivos .stamp.

Integração com makefiles simples ou outros sistemas de compilação
Neste caso, não se deseja usar o automake e, portanto, gtk-doc.mak. Será necessário chamar as ferramentas do gtkdoc na ordem correta nos makefiles devidos (ou outras ferramentas de compilação).

Etapas de compilação da documentação

DOC_MODULE=meep
// fontes foram alterados
gtkdoc-scan --module=$(DOC_MODULE) <source-dir=>
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml --source-dir=<source-dir>
// arquivos xml foram alterados 
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

Será necessário olhar no Makefile.am e no gtk-doc.mak para obter as opções extras necessárias.

Integração com sistemas de compilação CMake
GTK-Doc agora fornece um módulo GtkDocConfig.cmake (e o module GtkDocConfigVersion.cmake correspondente). Ele fornece um comando gtk_doc_add_module que você pode usar em seu arquivo CMakeLists.txt.
O exemplo a seguir mostra como usar este comando.

Exemplo de uso do GTK-Doc no CMake

find_package(GtkDoc 1.25 REQUIRED)

# Cria o alvo doc-libmeep.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Compila doc-libmeep como parte do alvo padrão. Sem isso, você precisaria
# executar explicitamente algo como `make doc-libmeep` para compilar os
# documentos.
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})