How to document your scheme modules with guile-lib

How to document your scheme modules with guile-lib

[Andy Wingo]

[-- Attachment #1: Type: text/plain, Size: 1908 bytes --]

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/

[-- Attachment #2: docs.mk --]
[-- Type: text/plain, Size: 934 bytes --]

clean-docs:
	rm -f $(doc).texi
	rm -f $(doc).info
	rm -f $(doc)scmfiles
	rm -f html-stamp
	rm -rf html
	rm -f $(addprefix $(doc).,aux cp cps fn fns ky log pdf pg pg toc tp tps vr vrs)
	rm -rf $(doc).html

EXTRA_DIST=$(doc).scm make-texinfo.scm make-html.scm docs.mk
DISTCLEANFILES=$(doc).texi $(doc)scmfiles

$(doc)scmfiles:
	guile --debug --use-srfi=13 -l $(srcdir)/$(doc).scm \
	 -c '(for-each (lambda (m) (format #t "~a.scm\n" (string-join (map symbol->string m) "/"))) (map car *modules*))' \
	 > $@
depfiles=$(addprefix $(top_srcdir)/src/,$(shell test ! -f $(doc)scmfiles || cat $(doc)scmfiles))

$(doc).texi: $(srcdir)/$(doc).scm $(doc)scmfiles $(depfiles)
	$(top_srcdir)/dev-environ $(srcdir)/make-texinfo.scm $(srcdir)/$(doc).scm >$@

html: html-stamp $(srcdir)/$(doc).scm $(depfiles)
html-stamp: $(scm-module-files)
	$(top_srcdir)/dev-environ $(srcdir)/make-html.scm $(srcdir)/$(doc).scm
	touch $@


[-- Attachment #3: guile-library.scm --]
[-- Type: text/x-scheme, Size: 5089 bytes --]

;; About the package
(define *name* "Guile Library")
(define *description* "Common modules for Guile Scheme")
(define *version* "0.1.3")
(define *updated* "16 November 2006")
(define *authors*
  '(("Andy Wingo" . "wingo at pobox.com")
    ("Richard Todd" . "richardt at vzavenue.net")))

;; Copying the documentation
(define *copyright-holder* "Andy Wingo, Richard Todd")
(define *years* '(2003 2004 2005 2006))
(define *permissions*
  "Permission is granted to copy, distribute and/or
modify this document under the terms of the GNU Free
Documentation License, Version 1.2 or any later version published
y the Free Software Foundation; with no Invariant Sections, no
Front-Cover Texts, and no Back-Cover Texts. A copy of the license
is included in the section entitled \"GNU Free Documentation
License\".")

;; Texinfo info
(define *texinfo-basename* "guile-library")
(define *texinfo-category* "The Algorithmic Language Scheme")
(define *extra-texinfo-menu-entries*
  '(("Copying This Manual")
    ("Concept Index")
    ("Function Index")))
(define *texinfo-epilogue*
  `((node (% (name "Copying This Manual")))
    (appendix "Copying This Manual")
    "This manual is covered under the GNU Free Documentation "
    "License. A copy of the FDL is provided here."
    (menu
     "* GNU Free Documentation License::  License for copying this manual")
    (include "fdl.texi")
    (node (% (name "Concept Index")))
    (unnumbered "Concept Index")
    (printindex (% (type "cp")))
    (node (% (name "Function Index")))
    (unnumbered "Function Index")
    (printindex (% (type "fn")))))

;; HTML foo
(define *html-relative-root-path* "../../")

;; The modules to document
(define *modules*
  '(((config load)
     "Loading configuration files")
    ((container nodal-tree)
     "A tree consisting of nodes with attributes")
    ((container delay-tree)
     "A nodal tree with lazily evaluated fields")
    ((debugging assert)
     "Helpful assert macro")
    ((debugging time)
     ;; FIXME: also in ice-9, this needs to go.
     "A simple macro to time the execution of an expression")
    ((graph topological-sort)
     "Routines to perform topological sorts")
    ((htmlprag)
     "Neil Van Dyke's permissive (\"pragmatic\") HTML parser")
    ((io string)
     "SLIB's IO routines dealing with strings")
    ((logging logger)
     "A flexible logging system")
    ((logging port-log)
     "A logger that outputs to a port")
    ((logging rotating-log)
     "A logger that rotates its output files")
    ((math minima)
     "A golden-section minimum finder")
    ((math primes)
     "Functions related to prime numbers and factorization")
    ((math rationalize)
     "Working with fractions")
    ((os process)
     "Spawning processes and capturing their output")
    ((scheme documentation)
     "Macros to define different kinds of variables with documentation")
    ((scheme session)
     "A more featureful " (code "(ice-9 session)"))
    ((search basic)
     "Classic search functions")
    ((statprof)
     "Statistical profiler")
    ((string completion)
     "Building blocks for tab completion")
    ((string soundex)
     "The SOUNDEX string categorization algorithm")
    ((string transform)
     "Beyond SRFI-13")
    ((string wrap)
     "A versatile string formatter")
    ((sxml apply-templates)
     "A more XSLT-like approach to SXML transformations")
    ((sxml simple)
     "Convenient XML parsing and serializing")
    ((sxml ssax)
     "Functional-style XML parsing for Scheme")
    ((sxml ssax input-parse)
     "The SSAX tokenizer, optimized for Guile")
    ((sxml transform)
     "A higher-order SXML transformation operator, "
     (code "pre-post-order"))
    ((sxml xpath)
     "XPath for SXML")
    ((term ansi-color)
     "Generate ANSI color escape sequences")
    ((texinfo)
     "Parse texinfo files or fragments into " (code "stexi") ", a "
     "scheme representation")
    ((texinfo html)
     "Transform " (code "stexi") " into HTML")
    ((texinfo indexing)
     "Extract an index from a piece of " (code "stexi"))
    ((texinfo nodal-tree)
     "Chunk a " (code "stexi") " document into pieces")
    ((texinfo plain-text)
     "Render " (code "stexi") " as plain text")
    ((texinfo serialize)
     "Render " (code "stexi") " as texinfo")
    ((texinfo reflection)
     "Enable texinfo across Guile's help system")
    ((text parse-lalr)
     "A LALR(1) parser written in Scheme")
    ((unit-test)
     "A JUnit-style unit testing framework")))
    ;; link to literate programming article

(define *module-sources*
  '(((sxml ssax) . "http://ssax.sourceforge.net/")
    ((sxml xpath) . "http://ssax.sourceforge.net/")
    ((sxml transform) . "http://ssax.sourceforge.net/")
    ((sxml apply-templates) . "http://ssax.sourceforge.net/")
    ((sxml ssax input-parse) . "http://ssax.sourceforge.net/")
    ((htmlprag) . "http://neilvandyke.org/htmlprag/")))

;; arch-tag: e493ad42-ad58-451c-a2d6-b17ba6c1d1d0

[-- Attachment #4: Makefile.am --]
[-- Type: text/plain, Size: 769 bytes --]

doc=guile-library

include docs.mk

info_TEXINFOS=guile-library.texi
guile_library_TEXINFOS=fdl.texi

www: html guile-library.pdf clean-www
	find www -name 'index.scm' -print \
	  | while read f; do \
              guile -l "$$f" -c '(make-index)' \
	        > `echo $$f | sed -e s,\.scm,\.html,`; \
	    done
	cp -a html www/doc/ref
	cp guile-library.pdf www/doc/

www-commit: www
	svn rm -m 'make www in guile-lib/docs' svn+ssh://wingo@svn.gna.org/svn/guile-lib/website
	svn import -m 'make www in guile-lib/docs' www svn+ssh://wingo@svn.gna.org/svn/guile-lib/website

clean-www:
	find www -name 'index.html' -print \
	  | while read f; do rm -f "$$f"; done
	rm -rf www/doc/ref
	rm -f www/doc/guile-library.pdf

clean: clean-docs clean-www

[-- Attachment #5: make-html.scm --]
[-- Type: application/x-shellscript, Size: 3726 bytes --]

[-- Attachment #6: make-texinfo.scm --]
[-- Type: application/x-shellscript, Size: 838 bytes --]

[-- Attachment #7: Type: text/plain, Size: 140 bytes --]

_______________________________________________
Guile-user mailing list
Guile-user@gnu.org
http://lists.gnu.org/mailman/listinfo/guile-user