Changes to "authors.html" for

Here are my changes to authors.html for  Don't
worry about the style-- theoretically this will look right once on; I'll discuss those details with jdub. 

It should be viewable with any old browser. My only question is:
        * How do I resolve conflicts between the and files from gtk+ and gtk-doc? 
Gtk+ has very simple makefiles in its docs/ and docs/reference
directories; the in gtk-doc/examples/ is huge and
scary. The from gtk+ uses the gtk-doc.m4 macro, while the
one in setting-up.txt (in the gtk-doc module) uses something else a
little longer and slightly unweildy.

What we need to figure out (assuming that there are canonical and
correct versions of these files (or file sections)) is how often those
files changes.

If the files change much (or at all) we might as well just tell people
"Use the ones from gtk+, check it out and copy." If they don't change,
then we can copy them to the gtk-doc module and the web pages.

What say ye?

Title: Writing Developer Documentation

Writing Developer Documentation

GNOME developer documentation is done using the gtk-doc package, which performs two basic tasks. First, it automates the creation of basic API documentation from source code and comments. Second, it provides an easy way for people to change and add to the auto-generated documentation without having to edit the source code itself.

The gtk-doc tools are not run by hand: you simply paste a few lines into your Makefiles, and then when you run a make install, a set of templates and documents are created. If you edit the templates, the tools will incorporate those changes into the documents the next time you build.

The gtk+ module in GNOME CVS is an excellent example of using gtk-doc.

File Formats and Dependencies

The templates and document output are in DocBook XML, just like user documentation. You will need a working DocBook package installed.

How to Set Up your Module to Use gtk-doc

These instructions are the same as the ones in the file "setting-up.txt" from the gtk-doc module in GNOME CVS. They assume that you will be using automake and autoconf.

  1. Install the gtk-doc package. Depending on your distribution, this will be called gtk-doc, gtkdoc, or gtk-doc-tools.
  2. Edit your file and paste in the lines found FIXME: Where?
  3. Create a directory in which you want your documentation to be built. The most commonly used directory is "docs/reference/".
  4. Create files for the directory or directories you created. Be sure to note all subdirectories in the SUBDIRS section, and all extra files in EXTRA_DIST.
  5. Add the new files to your, so that the autotools will find them during the build.

That's it. When you build the software, the API docs will be generated in the docs/reference directory.

In most GNOME projects, the "docs" directory is used for developer documentation-- build notes, project FAQs, and so forth. User documentation goes into the "help" directory.

Commenting your Code to Produce Automated Docs

When you build your project with gtk-doc, specially formatted comments are read and converted to documentation. What's the special format?

To document a function:

If you use emacs, you can add this elisp macro to your .emacs file, and use the shortcuts C-x4h or M-x gnome-doc-insert to put the right comment structure in for you.

The comment block will look like this:

 * function_name:
 * @par1:  description of parameter 1. These can extend over more than
 * one line.
 * @par2:  description of parameter 2
 * The function description goes here.
 * Returns: an integer.

Shortcuts and Syntax

In the XML templates and in the comment blocks, you can use shortcuts to highlight important pieces of information and link to other sections of the document.

The final output docs will link to the appropriate function or widget declarations if they exist.

Organizing Your Documentation

By default, gtk-doc structures the documentation it produces using the .h and .c files in your project: each file gets its own section in the document. To adjust the structure to fit your needs, edit the file myproject-sections.txt (the name will vary with your project name, of course). The tags

and are more or less self-explanatory.

Editing the Autogenerated Code

DocBook XML allows you a lot of flexibility. A complete DocBook reference is available at, but for the most part, you won't need more than a few tags.

The XML template files can be found in the tmpl/ directory. If you followed the GNOME default, that will be myproject/docs/reference/tmpl/.

Some of the most commonly used tags are:

  • <para>: The paragraph tag. Put it around any general piece of text.
  • <link>: Link to other items in your document using the XML id (unique within each document). For example: <link linkend="glib-Hash-Tables">Hash Tables</link>
  • <ulink>: URL link. For example, <ulink linkend=""></link>.
  • <example>: An example. The first part of your example should be a <title> tag, followed by one or more of <para> or <programlisting>.
  • <programlisting>: Put example code in here. It will be formatted verbatim.
  • <itemizedlist>: An itemized list like the <ul> tag in HTML. Each item is marked with <listitem> tags containing <para> tags. It is convenient to consider <listitem><para> as a single tag, since they are always together and nothing can come between them.
  • <type>: A data type.
  • <structname>: The name of a struct outside the GTK docs. Use the # shortcut for items inside the GTK docs.
Greater-than and less-than symbols in comment blocks are converted to "&gt;" and "&lt;" in the XML, for display as > and < in the final, human-readable display. It's difficult to use DocBook tags in your actual comment blocks; in general, just use the templates for that.

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]