Author: | Éric Faurot |
---|---|
Revision: | 1.6 |
Revision date: | 2004-03-02 |
This document describe the GGI documentation and web site framework in detail. It is intended for GGI contributors who need
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.
Besides a decent UNIX system, you'll need:
That's it.
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/
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.
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 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:
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
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.
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.
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.
Edit news.txt and add the news entry before existing ones. Try to respect the proposed notation.
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.
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.
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.