GPE Development Manual
Prev	Chapter 6. How to write Documentaion	Next

6.2. Developer Documentation

6.2.1. Work Setup

You don't need much on you host system to generate or modify GPE documentation. If you 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 useful to have latest gtk-doc-tools package installed to test the documentation build and verify the results.

If you intend to work on this manual you need some additional tools to convert the SGML sources into HTML or some other target format. Using docbook2html from the Debian docbook-utils package is a good choice.

6.2.2. Documentation in GPE Sources

Deverloper documentation consists of several tasks - the most important one is a proper documentation of all library interfaces to make libraries easy to use for other developers. Another very important task is to add comments in your source code to make it easier to understand. In particular sections which are not obvious or subject of frequent changes should be documented with comments. How to do this should be pretty obvious and so this section only deals with the documentation of library interfaces.

There are two ways to place documentation in the source:

1. Add special comments to the source code itself.
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). The Gnome project has a very nice description on how to use gtk-doc here: http://developer.gnome.org/arch/doc/authors.html

Adding documentation support to library source is really easy:

Create a subdirectory for the documentation. Most GPE libraries use "doc"
Add support for gtk-doc to configure.ac: "GTK_DOC_CHECK(1.2)"
Add the makefile in the documentation directory to the list of output files.
Copy gtk-doc.make to the documentation directory.
You can use gtkdocize (included in the gtk-doc package) and the Makefile.am template.
Change the Makefile.am file in doc to the correct source directory and to contain the correct product name.
Add all new files to EXTRA_DIST in the Makefile.am in their directory.

To add gtk-doc support to a piece of software without autotools do as follows: 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.

Prev	Home	Next
How to write Documentaion	Up	Framework Integration