Setting up your project
The next sections describe what steps to perform to integrate GTK-Doc into your project. Theses sections assume we work on a project called 'meep'. This project contains a library called 'libmeep' and an end-user app called 'meeper'. We also assume you will be using autoconf and automake. In addition section plain makefiles or other build systems will describe the basics needed to work in a different build setup.

Setting up a skeleton documentation
Under your top-level project directory create folders called docs/reference (this way you can also have docs/help for end-user documentation). It is recommended to create another subdirectory with the name of the doc-package. For packages with just one library this step is not necessary.
This can then look as shown below:

Example directory structure

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

Integration with autoconf
Very easy! Just add one line to your configure.ac script.

Integration with autoconf

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

This will require all developers to have gtk-doc installed. If it is okay for your project to have optional api-doc build setup, you can solve this as below. Keep it as is, as gtkdocize is looking for GTK_DOC_CHECK at the start of a line.

Keep 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)
])

The first argument is used to check for the gtkdocversion at configure time. The 2nd, optional argument is used by gtkdocize. The GTK_DOC_CHECK macro also adds several configure switches:
--with-html-dir=PATH : path to installed docs
--enable-gtk-doc : use gtk-doc to build documentation [default=no]
--enable-gtk-doc-html : build documentation in html format [default=yes]
--enable-gtk-doc-pdf : build documentation in pdf format [default=no]
GTK-Doc is disabled by default! Remember to pass the option '--enable-gtk-doc' to the next configure run. Otherwise pregenerated documentation is installed (which makes sense for users but not for developers).
Furthermore it is recommended that you have the following line inside your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project.

Preparation for gtkdocize

AC_CONFIG_MACRO_DIR(m4)

After all changes to configure.ac are made, update the configure file. This can be done by re-running autoreconf -i or autogen.sh.

Integration with automake
First copy the Makefile.am from the examples sub directory of the gtkdoc-sources to your project's API documentation directory ( ./docs/reference/<package>). A local copy should be available under e.g. /usr/share/doc/gtk-doc-tools/examples/Makefile.am. If you have multiple doc-packages repeat this for each one.
The next step is to edit the settings inside the Makefile.am. All the settings have a comment above that describes their purpose. Most settings are extra flags passed to the respective tools. Every tool has a variable of the form <TOOLNAME>_OPTIONS. All the tools support --help to list the supported parameters.

Integration with autogen
Most projects will have an autogen.sh script to setup the build infrastructure after a checkout from version control system (such as cvs/svn/git). GTK-Doc comes with a tool called gtkdocize which can be used in such a script. It should be run before autoheader, automake or autoconf.

Running gtkdocize from autogen.sh

gtkdocize || exit 1

When running gtkdocize it copies gtk-doc.make to your project root (or any directory specified by the --docdir option). It also checks you configure script for the GTK_DOC_CHECK invocation. This macro can be used to pass extra parameters to gtkdocize.
Historically GTK-Doc was generating template files where developers entered the docs. This turned out to be not so good (e.g. the need for having generated files under version control). Since GTK-Doc 1.9 the tools can get all the information from source comments and thus the templates can be avoided. We encourage people to keep documentation in the code. gtkdocize supports now a --flavour no-tmpl option that chooses a makefile that skips tmpl usage totally. Besides adding the option directly to the command invocation, they can be added also to an environment variable called GTKDOCIZE_FLAGS or set as a 2nd parameter in GTK_DOC_CHECK macro in the configure script. If you have never changed file in tmpl by hand and migrating from older gtkdoc versions, please remove the directory (e.g. from version control system).

Running the doc build
After the previous steps it's time to run the build. First we need to rerun autogen.sh. If this script runs configure for you, then give it the --enable-gtk-doc option. Otherwise manually run configure with this option afterwards.
The first make run generates several additional files in the doc-directories. The important ones are: <package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt.

Running the doc build

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

Now you can point your browser to docs/reference/<package>/index.html. Yes, it's a bit disappointing still. But hang-on, during the next chapter we tell you how to fill the pages with life.

Integration with version control systems
As a rule of thumb, it's the files you edit which should go under version control. For typical projects it's these files: <package>.types, <package>-docs.xml (in the past .sgml), <package>-sections.txt, Makefile.am.
Files in the xml/ and html/ directories should not go under version control. Neither should any of the .stamp files.

Integration with plain makefiles or other build systems
In the case one does not want to use automake and therefore gtk-doc.mak one will need to call the gtkdoc tools in the right order in own makefiles (or other build tools).

Documentation build steps

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

One will need to look at the Makefile.am and gtk-doc.mak to pick the extra options needed.

Integration with CMake build systems
GTK-Doc now provides a GtkDocConfig.cmake module (and the corresponding GtkDocConfigVersion.cmake module). This provides a gtk_doc_add_module command that you can set in your CMakeLists.txt file.
The following example shows how to use this command.

Example of using GTK-Doc from 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})