Project Setup
This Chapter describes the steps that are necessary to integrate GTK-Doc into your project. The integration of GTK-Doc into a project includes the following steps:
Preparation of the directory structure and creating required configuration files for your GTK-Doc documentation (see Setting up a skeleton documentation).
Adjusting the build system to build your documentation using the GTK-Doc tools. Multiple build systems are supported, in this manual we describe how to integrate GTK-Doc with Autotools, CMake, and plain Makefiles.
Adding GTK-Doc specific files to version control and deciding which files to ignore (see Integration with version control systems).
The following sections assume we work on a project called meep. This project contains two packages (or modules), a library called libmeep and an end-user app called meeper.

Setting up a skeleton documentation
A common convention is to place documentation into a folder called docs inside your top-level project directory. We usually distinguish between reference documentation intended for developers and an user manual intended for end-users. Again the convention is to have separate folders for both. We usually place the reference documentation in a folder named reference and the end-user manual in a folder named help as. According to the above convention the documentation for our libmeep package would be placed into: docs/reference/libmeep. For packages with just one library or application the documentation could also be placed directly into docs/reference. It is not mandatory to use the above convention, but if you choose to use a different directory structure you must adjust your build system configuration to match your directory structure.
In the following sections we will assume a directory structure for our meep project that uses the above conventions.

Example directory structure of meep project

meep/
  docs/
    reference/  # reference documentation
      libmeep/
      meeper/
    help/       # optional: user manual
      meeper/
  src/
    libmeep/
    meeper/

Integration with Autotools
Integration of GTK-Doc into an autotools-based build system requires the following steps:
Ensure that gtkdocize is run once before the configure script. If an autogen.sh script is present, adjust it to check for GTK-Doc and add a call to gtkdocize.
The main purpose of gtkdocize is to make the gtk-doc.make Makefile and the gtk-doc.m4 macro definition file available to the build system, either by copying or linking it into the project.
Add the necessary autoconf macros to configure.ac to enable GTK-Doc in your build system to allow configuration of GTK-Doc via the generated configure script.
Among others with registers the --enable-gtk-doc option with the configure script.
Create an automake script for each application or library in your project. In the example used in this documentation this step applies to both meeper and libmeep.
In the following sections, we will perform the above steps in reverse order. We start with the automake scripts and work our way up to configure.ac and autogen.sh. Then we show how enable Gtk-Doc in the build system and how to build the documentation.

Integration with automake
First copy the Makefile.am from the examples sub-directory of the gtkdoc-sources to your project's reference documentation directory (e.g. 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 packages repeat this for each one.
Do not forget to add each Makefile.am to the AC_CONFIG_FILES macro in configure.ac. For docs/reference/libmeep/Makefile.am you will need to add the entry docs/reference/libmeep/Makefile to AC_CONFIG_FILES.

Example directory structure with Makefiles.am

meep/
  docs/
    reference/  # reference documentation
      libmeep/
        Makefile.am
      meeper/
        Makefile.am
    help/       # optional: user manual
      meeper/
  src/
    libmeep/
    meeper/

Next, you need to customize the copied Makefiles and provide values for the various parameters in each Makefile.am. All settings have a comment above them that describes their purpose and how to customize the setting. Most settings are used to supply extra flags to the respective tools to which they apply. Every tool has a variable of the form <TOOLNAME>_OPTIONS (e.g. the tool gtkdoc-mkhtml has an option named MKHTML_OPTIONS). All the tools support --help to list the supported options.
The following list explains the most relevant options. Check the example Makefile.am for additional options.
DOC_MODULE is used to provide the name of the package that is being documentated (e.g. meeper, or libmeep).
DOC_SOURCE_DIR is used to specify the location of source directory which GTK-Doc searches for your API documentation. This will usually be DOC_SOURCE_DIR=$(top_srcdir)/src or a sub-directory of that directory.
HFILE_GLOB and CFILE_GLOB are used for dependencies. Each option take a file-glob (e.g. HFILE_GLOB=$(top_srcdir)/src/*.c). The documentation will be rebuilt if any of the matched files change.
EXTRA_HFILES allows to specify extra header files to include when scanning for API documentation, which are not found under DOC_SOURCE_DIR (e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h).
IGNORE_HFILES allows to specify header files or directories to ignore when scanning for API documentation. Use the basename of the file or directory (e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code_folder).
HTML_IMAGES allows to specify images files which will be copied into the html/ directory of the generated documentation. If your API documentation includes any images they need to be added to this option (e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png).
content_files allows to specify extra files that are included by $(DOC_MAIN_SGML_FILE) (e.g. content_files=running.xml building.xml changes-2.0.xml).
expand_content_files allows to specify files where gtk-doc abbreviations such as #GtkWidget are expanded (e.g. expand_content_files=running.xml).

Integration with autoconf
Integration with autoconf is very simple and includes one required step and an additional optional (but recommended) step. The first step is to add the GTK_DOC_CHECK macro to your configure.ac script. This registers several configure options to enable GTK-Doc and allows you to set default arguments for gtkdocize.
Make sure that the GTK_DOC_CHECK macro is not indented. The macro must start at the beginning of the line and should not start with whitespace.
The second step is to add the AC_CONFIG_MACRO_DIR(m4) to your configure.ac. This is not required but helps gtkdocize to automatically copy the macro definition (e.g gtk-doc.m4) which contains the GTK_DOC_CHECK macro to your project's macro directory. Without this, the GTK_DOC_CHECK macro might not be found and you would need to explicitly tell the aclocal tool where to find the macro definition file.

Minimal integration with autoconf

# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])

The above example works, but will require all developers to have gtk-doc installed. A better way is to make building the documentation optional as shown in the next example:

Integration with optional gtk-doc dependency

m4_ifdef([GTK_DOC_CHECK], [
# recommended: set m4 directory
AC_CONFIG_MACRO_DIR(m4)
# optional: register gtk-doc in configure
GTK_DOC_CHECK([1.28])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])

The first argument is used to check for the Gtk-Doc version 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).
After all changes to configure.ac are made, update the configure file. This can be done by re-running autogen.sh.

Integration with autogen
Most projects will have an autogen.sh script to setup the build infrastructure after the project was checked out from a version control system (such as git or svn). GTK-Doc comes with a script called gtkdocize which can be used to copy the necessary files needed by Gtk-Doc to the source directory.
It should be run before autoreconf, autoheader, automake or autoconf.

Running gtkdocize from autogen.sh

gtkdocize || exit 1

Conditionally run gtkdocize from autogen.sh

GTKDOCIZE=$(which gtkdocize 2>/dev/null)
if test $? -ne 0; then
  echo "No gtk-doc support found. You can't build the docs."
else
  $GTKDOCIZE || exit 1
fi

When running gtkdocize it copies gtk-doc.make to your project root (or any directory specified by the --docdir option).
gtkdocize checks your configure.ac script for the GTK_DOC_CHECK macro. The GTK_DOC_CHECK macro can be used to pass extra arguments to the gtkdocize script. the 2nd parameter in the GTK_DOC_CHECK macro.
Alternatively, additional arguments can also be passed to gtkdocize via the GTKDOCIZE_FLAGS environment variable, or by directly specifying them to gtkdocize in autogen.sh.

Executing GTK-Doc from the Build System
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. With this initial setup you will only see a very simple document. The next chapter will teach you how to add API documentation to your code via special comment blocks. The Chapter afterwards introduces additional files and shows how to edit the master template to add additional chapters and sections to your documentation files.

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})

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 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.