Here are my changes to authors.html for developer.gnome.org. Don't
worry about the style-- theoretically this will look right once on
gnome.org; 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 configure.in and
Makefile.am files from gtk+ and gtk-doc?
Gtk+ has very simple makefiles in its docs/ and docs/reference
directories; the Makefile.am in gtk-doc/examples/Makefile.am is huge and
scary. The configure.in 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?
Yours,
Aaron
Title: 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.
Tip:
The gtk+ module in GNOME CVS is an excellent example of using gtk-doc.
The templates and document output are in DocBook XML, just like user documentation. You will need a working DocBook package installed.
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.
That's it. When you build the software, the API docs will be generated in the docs/reference directory.
Tip:
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.
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. */
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.
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
DocBook XML allows you a lot of flexibility. A complete DocBook reference is available at docbook.org, but for the most part, you won't need more than a few tags.
Tip:
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:
Tip:
Greater-than and less-than symbols in comment blocks are converted to ">" and "<" 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.