Documenting GGI

Author : Éric Faurot
Revision : 1.21
Revision date : 2007-04-05

This document describe the GGI documentation and web site framework in detail. It is intended for GGI contributors who want to update or complete the documentation and other written material.

Building it all

When working on the documentation, it is better to test that everything will work fine before commiting changes to the main repository. So before describing the whole documentation framework in detail, we will show how to generate everything locally for testing purpose.

Software requirements

Besides a decent UNIX system, you'll need:

  • a recent version of the ggi-project cvs tree, especially the html module,
  • a decently recent version of python (now 2.3 or higher).
  • docutils 0.4, which is normally packaged in every distribs.

You will need to put a .ggisettings file in your HOME directory, so that the build systems knows where to find and put files. See the template file html/infrastructure/ggisettings and adapt to your needs.

Building the site

Damn easy. Go to the html/infrastructure directory in the GGI cvs tree and type:

make site

It will populate the given output dir with html files for the site, all documentation, and copy all necessary files. Note that all generated html pages will use relative url to link to each other. Only new or updated pages are regenerated.

Building the manpages

Not more complicated.

make manpages

This will update all manpages for all versions of GGI libraries. The pages will go in the correct 'doc/man', replacing older ones if they exist. Note that 'Makefile.am' will be automaticaly generated.

Site contents

Mostly everything is written using ReStructured Text format, with custom features. Please refer to the docutils site for explanation on the format. Also, try to respect the coding style of the GGI documentation, such as the characters used for section underlining. Anyway, you will almost always be able to use an existing file as a template for new ones.

The documentation framework has a couple of additions to the base docutils packages. In particular, the following interpreted roles are used:

':func:`ggiOpen`'

Specifies a function or program name. Anything callable or executable. It will be rendererd as ggiOpen.

':val:`DL_LAZY`'

Specifies a value, a constant, a path, a filename... It will be rendererd as DL_LAZY

':var:`HOME`'

A variable name, structure member, parameter or argument. Anything that can hold a value. It will be rendererd as HOME. The equivalent ':p:' (parameter) notation can also be used.

':man:`giiMTInit(3)`'

A reference to a manpage. This is used to automatically generate links to internal documentation. Examples: giiMTInit(3), fcntl(2).

To ease things, when the default role is used (as in '`ggInit`'), the build framework, will try to determine what the token refers to, by looking for manpages entries, library names, keywords... If nothing relevant is found, it will consider the token as a value. Examples: ggInit(3), libggi(7), NULL

Adding a simple page to the site

If new pages are to be added in the site, simply add a pagename.txt file in the html directory. The file will be automatically converted to html with other .txt files. Don't forget to add a reference to it somewhere though, otherwise chances are that the page will never be found.

Navigation sequence can be given in a page, via the 'navigation' directive. This might be extended in the future to include keywords, etc... All fields are optional:

.. navigation::
   :next:  credits.html
   :prev:  news.html
   :up:    index.html

Adding a document

Documentation pages (not library references) are just like normal pages, except that they resides in documentation and they are named with topic-<whatever>.txt. To add a document, you just need to write the file, then add a reference to it in documentation/index.txt.

Adding a news item

Edit news.txt and add the news entry before existing ones. Try to respect the proposed notation.

Making a release for a package

When a new release is made for a package, simply add the corresponding <libname>-<version>.txt file in packages/. The index is automatically generated, as well as fix-counting.

Adding a new package

To add a new package to the list of packages, put a <package-name>.txt file in packages/, and reference it in packages/index.txt at the correct place. The packages files can be used to summarize noticable changes. They should be updated when significant changes are made in the cvs repository.

For releases to be handled properly, the package should also be listed in 'html/infrastructure/packages'.

Documenting a package

Packages are documented by a set of manpages, generated automatically from there ReST versions. The entry to a package documentation is the single file named <packagedir>/doc/<packagename>.txt. Note that some package may actually provide several package documentation when it makes sense. For example LibGII provides both libgg(7) and libgii(7) documentation.

The top level file for a package documentation must have a title. The first sectioning level is used to group the manpages into coherent sets (for example, different API levels, modules, ...). These sections may begin with normal text flow that will only appear on the html index for this package.

The second sectioning level is used to create individual manpages. After the section name, a custom manpage directive must be inserted. The syntax is fairly simple. The first argument is the manpage volume, the second one is the name of the main entry, and additional names are entries that will refer to this page. This gives something like

.. manpage:: <volume> <mainentry> [ <link> <link> ... ]

All in one line. The rest is normal ReST formatting. As usual, it is strongly advised to look at existing documentation and use that as templates.