How to document your scheme modules with guile-lib

[Andy Wingo]

Hi all,

I just wrote a bit about how you can get great on-line help, printed
docs, web docs, and info, all autogenerated from your source files. The
article is here:

  http://wingolog.org/archives/2006/11/17/high-on-sodium-vapor

I'd like to write a bit on how those docs are made. It's pretty easy,
and I think the output is nice.

First, how to document. A module's documentation is taken from its
commentary and from the docstrings on all of its exported variables. The
module commentary is gotten by (module-commentary '(modname)), which
parses the text between

;;; Commentary:

and

;;; Code:

The text between Commentary and Code has any initial ;; split off, which
allows you to have a commentary like this:

;;; Commentary:
;; This module foo bar @code{baz} @xref{foo}. asdfasd 
;;; Code

The other documentation source is the documentation on objects
themselves, via (object-documentation foo). Guile-lib exports some
macros in (scheme documentation) that allow you to document normally
undocumented things, like variables or generics. See
http://home.gna.org/guile-lib/doc/ref/scheme.documentation/ for more
info there.

To get integration with guile's help system, you have to load up (scheme
session), which makes (help foo) return more useful information.

>From there I wrote some scripts to generate texi and html output, which
are in guile-lib/doc and are attached. I'm actually attaching five
files:

guile-library.scm: The configuration file for the docs build
Makefile.am: automake foo, adjust to fit
docs.mk: Docs makefile foo, shouldn't need tweaking
make-html.scm: A script to make OK-ish HTML docs
make-texinfo.scm: A script to make a nice texinfo document

All you have to do is dump all those files in a dir, modify
guile-library.scm to suit (and rename), and modify a couple of things in
Makefile.am. Voila, self-documenting projects :)

Regards,

Andy.
-- 
http://wingolog.org/

docs.mk
Description: Text document

guile-library.scm
Description: Text Data

Makefile.am
Description: Text document

make-html.scm
Description: application/shellscript

make-texinfo.scm
Description: application/shellscript