How to generate lisp docs with Albert

When making your ASDF system-file, add extra properties that Albert can understand to configure the behaviour of Albert. This is from the current version of Langband:

(asdf:defsystem :langband-engine
    :name "Langband Engine"
    :author "Stig E Sandoe"
    :version "0.1.7"
    :licence "GPL"
    :properties ((#:author-email . "stig@langband.org")
		 (#:date . "Summer 2003")
		 ((#:albert #:output-dir) . "albert-docs/")
		 ((#:albert #:formats) . ("docbook"))
		 ((#:albert #:docbook #:template) . "book")
		 ((#:albert #:docbook #:bgcolor) . "white")
		 ((#:albert #:docbook #:textcolor) . "black")
		 )
    :components
    ...)

The above preferences ensures that I get a Docbook 'book' as output with correct info for any headers/title-pages/etc. To see a list of understood properties, check this page.

To generate the documentation for langband I do:

* (in-package :cl-user)

* (require :albert)
* (load "langband-engine.asd")
* (albert:document-systems :langband-engine) ;; changed from v0.2

Albert will generate DocBook documentation in your chosen directory, in this case albert-docs/. To generate HTML with jade you can do this:

jade -d ALBERT_PATH/data/albert.dsl -t sgml ALBERT_PATH/data/xml.dcl book.xml

For Langband this results is this reference documentation. The ALBERT_PATH for the Debian package is /usr/share/albert

IMPORTANT: To get decent-looking docs you need to do two things.
1. Copy albert.css file from the albert-distribution (or /usr/share/albert/) to where you have the HTML documents.
2. Copy or link the icons/ directory to where you have the HTML documents to get the navigation icons used in the example docs.

To generate documentation in a printable format (not as far in development as the HTML output), you can try these commands:

jade -d ALBERT_PATH/data/print-albert.dsl -t tex ALBERT_PATH/data/xml.dcl book.xml
jadetex book.tex

Note: The actual docme.lisp script in langband is a bit more complicated and the latest version is here. It also provides examples of how to ignore some calls in the method-listings, as well as special handling of a few langband-specific macros. See the FAQ for more explanation for some of the extras.


stig@users.sourceforge.net
SourceForge.net Logo