GPE Documentation Mini-HowTo

Some notes about documenting the GPE libraries.

Work setup

You don't need much on you host system to generate or modify GPE documentation. If you only intend to help documenting a library which has documentation stuff in CVS you only need your favourite text editor and cvs.

To add documentation support or build the documentation from source you will need make, gtk-doc and the packages these depend on (perl, jade and some docbook stuff).
Running Debian just run 'apt-get install gtk-doc-tools'. It is a good idea to have latest gtk-doc-tools package installed.

Documentation in GPE source

There are two ways to place documentation in the source:
  1. Add special comments to the source code itself. The layout is described here.
  2. Add the documentation to the template files.
These files are located in the doc/tmpl/ subdirectory of each library after adding documentation support. You should prefer to keep the major part of the documentation in the source code to make it easier to keep it up to date. Use the external files for generic which is not related to a particular entitiy in the code (e.g. a function).

Adding documentation support to library source is really easy:

If you use autotools you need to add to add gtk-doc support to your configure.ac. You can use gtkdocize (included in the gtk-doc package) and the Makefile.am template.

To do it without autotools do this:

First add a section to the main Makefile adding the "doc" target: 

doc:
	make -C doc PACKAGE=$(PACKAGE)

.PHONY: doc

Create the 'doc' subdirectory and add a Makefile to it. This file may look similar to this:

all: doc
doc:
	gtkdoc-scan --module=$(PACKAGE) --source-dir=../gpe --output-dir=.
	gtkdoc-mktmpl --module=$(PACKAGE)
	gtkdoc-mkdb --module=$(PACKAGE) --source-dir=../gpe --tmpl-dir=tmpl --output-format=xml --main-sgml-file=$(PACKAGE)-docs.sgml --sgml-mode
	gtkdoc-mkhtml $(PACKAGE) $(PACKAGE)-docs.sgml
clean:
	rm -f *.html sgml/* xml/* *.stamp
This should be sufficient in most cases. Only the location of the header sources that contain the declarations to document need to be set correctly.

Now you are ready to run 'make doc' the first time. Note: With this simple Makefile running make in the doc subdirectory itself will fail. Run 'make doc' in the toplevel directory only.
It is a good idea to start documenting with the toplevel sgml file gtk-doc creates in 'doc'. If you are unsure what to add there look at the file libgpewidget-docs.sgml in libgpewidget source.