Atdoc generates documentation for Common Lisp packages. It extracts documention strings written using a custom markup language and generates HTML pages, TeX documents, and Info files.

atdoc was written by David Lichteblau and is available under an X11-style license.

Output formats

Atdoc can currently generate documentation in these formats:

Download and Installation

Download an atdoc tarball, or get it from git: http://www.lichteblau.com/git/atdoc.git (gitweb)

atdoc needs Closure XML, Split sequence, Slime's swank, Xuriella XSLT, Closer-MOP, and their dependencies.

ASDF is used for compilation. Register the .asd file, e.g. by symlinking it, then compile atdoc using asdf:operate. 

$ ln -sf `pwd`/atdoc.asd /path/to/your/registry/
* (asdf:operate 'asdf:load-op :atdoc)

Usage

Please refer to the API documentation for details, or see below for an example.

Sample Documentation

As an example, I have chosen code from the book Lisp (3rd edition) by Winston and Horn. You can find the code with an ASDF definition in the example/ subdirectory of the atdoc sources so that you can easily compile it yourself. The code included is the Blocks World, from chapters 21 ("The Blocks World with Classes and Methods") and 22 ("Answering Questions about Goals"). Note that the source code from the book has been taken from the publically available lisp3 tarball and is covered by its own license, different from the license of atdoc.

The examples linked above were generated using:

(atdoc:generate-html-documentation
   '(:blocks-world :blocks-world-goals)
   output-directory
   :index-title "Blocks World API reference"
   :heading "The Blocks World"
   :single-page-p t      ;optional
   :include-internal-symbols-p nil)

and

(atdoc:generate-latex-documentation
   '(:blocks-world :blocks-world-goals)
   output-directory
   :title "The Blocks World")
(atdoc:generate-info-documentation
   '(:blocks-world :blocks-world-goals)
   output-directory
   :name "blocks-world"
   :title "The Blocks World")

Writing a documentation string

Here is an example of what the documentation of print-object could look like using atdoc: 

@arg[object]{an object}
@arg[stream]{a @class{stream}}
@return{@code{object}}

@short{The generic function @fun{print-object} writes the printed
representation of @code{object} to @code{stream}.}

The function print-object is called by the Lisp printer; it should not
be called by the user.

(...)

@see{pprint-fill}
@see{pprint-logical-block}
(...)

Note that parts of the documentation strings are just documentation text, which is will be included in a section "Details" of the page. Other parts, however, are not part of the actual text, and will be extracted from the documentation string as the first step of processing it. In this case, @arg, @return, and @see are the tags that will be removed. All @arg tags will be collected into a section about the function's arguments, all @see tags will be collected together will all @fun and @class references into a "See also" section.

Tags for use only in the docstring of a package itself:

Tags that will be extracted into their own sections:

Tags for use in the documentation text:

Tags that are passed through to HTML:

The Atsign syntax

Atdoc looks for markup tags start with an at-sign, in either a long or a short form.

The short form looks like this: 

@return{the computed result}

The long form can be convenient for multiple lines of text: 

@begin{return}
the computed result
@end{return}

Except for the additional whitespace due to line breaks in the second example, the two forms are completely interchangeable. Behind the scenes, both produce an XML element with tag name result, <result>the computed result</result>

Both forms take an optional argument, written with brackets: 

@a[http://www.cliki.net]{Cliki}
(gets translated into <a a="http://www.cliki.net">Cliki</a>, until the XSLT stylesheets rename a into href) 
@begin[Title]{section}
body
@end{section}
(gets translated into <section section="Title">body</section>)

The atsign also escapes special characters: 

closing braces need to be escaped: {n,m@}

Multiple line breaks delimit paragraphs: 

First paragraph.

Second paragraph.

Recent changes

2008-11-30

2007-05-13