Atdoc generates documentation for Common Lisp packages. It extracts documention strings written using a custom markup language and generates HTML pages.
atdoc was written by David Lichteblau and is available under an X11-style license.
Download and Installation
Download an atdoc tarball.
atdoc needs Closure XML, Split sequence, Slime's swank, and requires an installation of xsltproc.
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)
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.
See the atdoc-generated documentation for the Blocks World.
It was generated using this atdoc invocation:
(atdoc:generate-documentation '(:blocks-world :blocks-world-goals) "/home/david/src/lisp/atdoc/example/" :index-title "Blocks World API reference" :heading "The Blocks World" :css "orange-sans.css")
Usage
atdoc exports only one function, atdoc:generate-documentation. It accept the following arguments (see above for an example):
- packages (required). List of package designators. Focumentation will be generated for these packages.
- directory (required). A pathname specifying a directory. Multiple files will be created in this directory, and overwritten if they already exist.
- index-title (keyword argument). This string will be used as the <title> of the main page, index.html. (Other pages will be named according to the object they are documenting.)
- heading (keyword argument). This string will be used as a visible title on top of every page.
- css (keyword argument). A pathname or string pointing to a cascading stylesheet (CSS) file. This file will be copied to the target directory under the name index.css. If this argument is a string and does not start with a dot, it will be taken as namestring relative to the atdoc/css directory.
- logo (keyword argument). This optional URI string will should be a relative reference to an image in the target directory and will be inserted as an image element at the upper left corner of every page.
Included Stylesheets. Several CSS files are included as an example, including blue-serif.css, orange-sans.css, and boxy.css.
IANAA (I am not an artist) and would welcome submission of better stylesheets.
Generated files. atdoc will create the following files in the target directory:
- index.html. This is the main page, which shows a list of all packages and a symbol index for all their exported symbols.
- pages/*.html. Every package, class, function, and variable is documented on its own page in this subdirectory.
- index.css. The is a copy of the file specified by the css keyword argument.
- .atdoc.*. Temporary files (can be deleted safely).
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:
- @section[title]: Generates a sub-heading called title. A table of contents will be generated at the top of the package pages listing the sections.
- @aboutfun{name}: Insert the lambda list of function name and its short description (the contents of @short in its docstring).
- @aboutclass{name}: Insert the name of class name and its short description (the contents of @short in its docstring).
Tags that will be extracted into their own sections:
- @arg[name]{description}: Will be moved into the "Arguments" section.
- @return{description}: Will be moved into the "Return Value" section.
- @see{name}: Link to the function named name. Syntactically like @fun, this tag will be moved into the "See also" section.
- @see-slot{name}: Similar to @see, this tag specifies a slot reader function for the class it is used in, and will be moved into a "Slot Access Functions" sections. In addition, a section "Inherited Slot Access Functions" will be shown for subclasses.
- @see-constructor{name}: Similar to @see, this tag specifies a function creating instances of current class, and will be moved into a "Returned By" section.
Tags for use in the documentation text:
- @short{text}: Copies text into the output normally, but will also extract it for use with @aboutfun and @aboutclass.
- @code: In-line lisp code, will be formatted using a fixed-width font.
- @a[href]: Hyperlink. This tag accepts an argument, the URL to be used as the href attribute.
- @itemize, @item: Like <ul> and <li>;
- @fun{name}: Link to the function named name, read as a symbol into the current package (qualify with a package name to reference other packages included in the same documentation).
- @class{name}: Link to the class named name. Works like @fun.
- @variable{name}: Link to the special variable named name. Works like @fun.
Tags that are passed through to HTML:
- @pre: Preformatted section, e.g. for source code listings.
- @b: Bold font.
- @em: Italic font.
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.