doc/setting-up.txt

   1 Note
   2 ====
   3
   4 There is now a user manual which can be read using yelp and can be found under
   5 'development'. Please refer to this documentation for up-to-date information.
   6
   7
   8 How to Set Up an Application or Library to use GTK-Doc
   9 ======================================================
  10
  11 This assumes that you are using autoconf & automake to build your package,
  12 and already have gtk-doc installed properly.
  13
  14
  15 1. Add this line to your autogen.sh, before the calls to autoheader, automake
  16    or autoconf:
  17
  18       gtkdocize || exit 1
  19
  20    If you are using gnome-autogen.sh it already runs gtkdocize for you.
  21    If you don't have an autogen.sh script you may need to run gtkdocize
  22    manually. (All gtkdocize does is copy gtk-doc.make to your project.)
  23
  24
  25 2. Add this line to your configure.in (somewhere before the call to AC_OUTPUT)
  26
  27        GTK_DOC_CHECK(1.0)
  28
  29    The number in brackets is the minimum version of gtk-doc required.
  30
  31
  32 3. Create a directory in your project where you want the docs to be built,
  33    e.g. 'myproject/docs/reference'. If you want to create several separate
  34    pieces of documentation you can create subdirectories for each one here.
  35    (e.g. GTK+ has subdirectories for gtk, gdk and gdk-pixbuf.)
  36
  37
  38 4. Copy examples/Makefile.am to this directory (or subdirectories) and edit
  39    the variables at the top of the file. (See the GTK+ source for an example.)
  40
  41
  42 5. Add the new Makefile(s) to your configure.in's AC_OUTPUT call, and make sure
  43    all the SUBDIRS variables are set properly so the docs directory is built.
  44
  45
  46 6. If your library or application includes GtkObjects/GObjects, and you want
  47    their signals, arguments/parameters and position in the hierarchy to be
  48    documented:
  49
  50    Create a MODULE.types file in the docs directory, e.g. "myproject.types".
  51    This should contain any '#include' directives needed to compile a program
  52    with your module, and a list of functions to initialize all of the widgets
  53    and objects in the library. For example, the gtk.types file starts like
  54    this:
  55
  56         #include <gtk/gtk.h>
  57
  58         gtk_accel_label_get_type
  59         gtk_adjustment_get_type
  60         gtk_alignment_get_type
  61         gtk_arrow_get_type
  62
  63 =============================================================================
  64
  65 That's it! If you now build the application or library you should get a
  66 complete set of documentation. gtk-doc is normally off by default so you
  67 may have to pass '--enable-gtk-doc' to autogen.sh or configure.in.
  68
  69 (Note that due to a problem with make the build may fail the very first time
  70 it is run, but if you run make again it should work. It only fails because
  71 there are no files in the tmpl/ directory initially. As soon as these are
  72 created it works fine.)
  73
  74
  75 You can tweak the output in several ways:
  76
  77  o modify the main SGML file to add introductory sections or to split the
  78    documentation into several chapters.
  79
  80  o modify the MODULE-sections.txt file to rearrange the documentation into
  81    different sections or a different order (see sections-file.txt for info).
  82
  83  o add a MODULE-overrides.txt to override particular declarations.
  84
  85
  86 Damon