Editando o documento mestre
O Gtk-Doc produz documentação em DocBook SGML/XML. Ao processar os comentários inseridos nos fontes, as ferramentas do GTK-Doc geram uma página de documentação por classe ou módulo como um arquivo separado. O documento mestre os inclui e os coloca em uma ordem.
Enquanto o Gtk-Doc cria um modelo de documento mestre para você, execuções posteriores não vão tocá-lo novamente. Isso significa que se pode estruturar a documentação livremente. Isso inclui agrupamento de páginas e adição de páginas extras. O Gtk-Doc agora possui uma suíte de teste, na qual também o documento mestre é recriado do zero. É uma boa ideia verificar isso de tempo em tempo para ver se há itens a serem introduzidos lá.
Não crie tutoriais como documentos extras. Apenas escreva capítulos extras. O benefício de embutir diretamente o tutorial para sua biblioteca na documentação da API é que é mais fácil vincular o tutorial a um símbolo da documentação. Além disso, as chances são mais altas que o tutorial obtenha atualizações junto com a biblioteca.
Então, quais são as coisas para se alterar dentro do documento mestre? Para começar é apenas um pouco. Existem alguns mantedores de espaço (texto em colchetes) que você deve cuidar.
<bookinfo> <title>Manual de referência do NOMEDOMÓDULO</title> <releaseinfo> for NOMEDOMÓDULO [VERSÃO] A última versão desta documentação também pode ser encontrada on-line em <ulink role="online-location" url="http://[SERVIDOR]/NOMEDOMÓDULO/index.html">http://[SERVIDOR]/NOMEDOMÓDULO/</ulink>. </releaseinfo> </bookinfo> <chapter> <title>[Insira o título aqui]</title>
Além disso, alguns elementos de opção são criados na forma comentada. Você pode revisá-los e habilitá-los como preferir.
<!-- habilite isso se você usa anotações do gobject introspection <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> -->
Finalmente você precisa adicionar nova seção sempre que você a introduzir. A ferramenta gtkdoc-check vai lembrar você de arquivos xml recentemente gerados que ainda não foram incluídos na documentação.
<chapter> <title>minha biblioteca</title> <xi:include href="xml/object.xml"/> ...