===============
Documenting GGI
===============

:Author: ric Faurot
:Revision: $Revision: 1.6 $
:Revision date: $Date: 2004/03/02 12:36:24 $

.. contents::
   :depth: 1

This document describe the GGI documentation and web site framework
in detail. It is intended for GGI contributors who need

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 (2.2 or higher)
- The development snapshot of `docutils`. Stable release will not work,
  oddly enough.

That's it.

Building the site
-----------------

Damn easy.

::

  python www.py <output dir>

It will populate the given output dir with html files.  We assume that
your current working directory is the `html` directory of the ggi
repository. You can also set the `GGIWWW` environment variable if you
are mirroring the site. The default is `http://www.ggi-project.org/`

Building the manpages
---------------------

Not more complicated.

::

  python manpage.py <filename> <output dir> [version]

Here `filename` is the path to the entry file of the package you are
generating the manpages for. The manpages will be put in the given
output dir. If these are the pages for a specific release, the version
may be given. By default it will be set to::

  `basename <filename> .txt`-current

To generate html manpages instead, use::

  python html.py <filename> <output dir> [version]

It will create an additional `index.html` listing all manpages.


Using the default Makefile
--------------------------

The `html` repository provides a Makefile that makes it easy to
generate site and manpages for specific packages version.  The
following targets are provided to generate various html pages:

`all`
	This generates the online site and all html manpages.

`site`
	Generates only the site pages, no html manpage.

`all-html`
	Generates html manpages for all packages.

`<repository>-html`
	Generates html manpages for all packages in a given repository.

`<package>-html`
	Generates html manpages for a specified package.

All HTML are affected by two environments variables that specify where
things goes: `DEST`, which specifies the directory where html files
will be put (defaults to `/tmp/ggisite`), and `WWW` that defines the
base URL to browse the generated site (defaults to `file://$(DEST)`).

These targets are used to generate manpages:

`all-man`
	Generates all manpages

`<repository>-man`
	Generates manpages for all packages in a given repository.

`<package>-man`
	Generates manpages for a specified package.

The manpages will always go into the `doc/man` directory of the
packages.

For all targets, the `CVS` variable points to the root of the ggi
repository. By defaults, is is set to `..`. Change this value if you
want to use an alternate tree. The path for individual package may
also be specified through environment variables, namely `GG`, `GII`,
`GGI`, `GALLOC`, `GGIMISC`, `GGIBUF`, `GGIBLT`, `GGIOVL`.  Finaly, if
manpages are generated (`-html` or `-man` targets), the version number
for individual packages can be specified, using the same variable name
suffixed by `_V`. The default value is `current`. The special variable
`DEFAULT_V` is used to define package versions by default (`current`
if unspecified).

For example, this generates the manpages marked as stable for ggi core
packages in `/ggi/stable/tree`::

  CVS=/ggi/stable/tree DEFAULT_V=stable make ggi-core-man

This is used to prepare the manpages for new versions of ggi and gii::

  CVS=/ggi/stable/tree GGI_V=2.0.5 GII_V=0.8.5 make  gg-man gii-man ggi-man

Site contents
=============

Mostly everything is written using ReStructured Text format, with
custom additions discussed later.  Please refer to their 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.


Adding a simple page
--------------------

If new pages are to be added in the site, simply add a `pagename.txt`
file in the base 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.

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 `releases/`. 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 release to be handled properly, the package should also be listed
in `www.py`, in the `libs` tuple.

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` and
`libgii` 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, with two
additionnal inline markup tags:

::

  :p:`argptr`

  :man:`giiMTInit(3)`


The first one is used to name a function parameter, the second one is
used to construct a reference to another manpage. Not that the `NAME`
section of the manpage will automatically be generated.

As usual, it is strongly advised to look at existing documentation and
use that as templates.
