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/
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 $@
;; 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
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://[EMAIL
PROTECTED]/svn/guile-lib/website
svn import -m 'make www in guile-lib/docs' www svn+ssh://[EMAIL
PROTECTED]/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
make-html.scm
Description: application/shellscript
make-texinfo.scm
Description: application/shellscript
_______________________________________________ Guile-user mailing list Guile-user@gnu.org http://lists.gnu.org/mailman/listinfo/guile-user
