Note
====
There is now a user manual which can be read using yelp and can be found under
'development'. Please refer to this documentation for up-to-date information.
How to Set Up an Application or Library to use GTK-Doc
======================================================
This assumes that you are using autoconf & automake to build your package,
and already have gtk-doc installed properly.
1. Add this line to your autogen.sh, before the calls to autoheader, automake
or autoconf:
gtkdocize || exit 1
If you are using gnome-autogen.sh it already runs gtkdocize for you.
If you don't have an autogen.sh script you may need to run gtkdocize
manually. (All gtkdocize does is copy gtk-doc.make to your project.)
2. Add this line to your configure.in (somewhere before the call to AC_OUTPUT)
GTK_DOC_CHECK(1.0)
The number in brackets is the minimum version of gtk-doc required.
3. Create a directory in your project where you want the docs to be built,
e.g. 'myproject/docs/reference'. If you want to create several separate
pieces of documentation you can create subdirectories for each one here.
(e.g. GTK+ has subdirectories for gtk, gdk and gdk-pixbuf.)
4. Copy examples/Makefile.am to this directory (or subdirectories) and edit
the variables at the top of the file. (See the GTK+ source for an example.)
5. Add the new Makefile(s) to your configure.in's AC_OUTPUT call, and make sure
all the SUBDIRS variables are set properly so the docs directory is built.
6. If your library or application includes GtkObjects/GObjects, and you want
their signals, arguments/parameters and position in the hierarchy to be
documented:
Create a MODULE.types file in the docs directory, e.g. "myproject.types".
This should contain any '#include' directives needed to compile a program
with your module, and a list of functions to initialize all of the widgets
and objects in the library. For example, the gtk.types file starts like
this:
#include <gtk/gtk.h>
gtk_accel_label_get_type
gtk_adjustment_get_type
gtk_alignment_get_type
gtk_arrow_get_type
=============================================================================
That's it! If you now build the application or library you should get a
complete set of documentation. gtk-doc is normally off by default so you
may have to pass '--enable-gtk-doc' to autogen.sh or configure.in.
(Note that due to a problem with make the build may fail the very first time
it is run, but if you run make again it should work. It only fails because
there are no files in the tmpl/ directory initially. As soon as these are
created it works fine.)
You can tweak the output in several ways:
o modify the main SGML file to add introductory sections or to split the
documentation into several chapters.
o modify the MODULE-sections.txt file to rearrange the documentation into
different sections or a different order (see sections-file.txt for info).
o add a MODULE-overrides.txt to override particular declarations.
Damon
Generated by dwww version 1.15 on Sat May 18 13:13:51 CEST 2024.