This is a simple but flexible modular document generator for Common Lisp, because I couldn't find something similar:

(gendoc (:output-filename "docs.html" :css "simple.css") (:mdf "") (:mdf "") (:apiref :some-package :another-package) (:mdf ""))

Of some interest is probably the API reference generator:

(defun some-function (X) "=> output-forms This takes `X` and produces *output-forms*" ...)

The docstring is processed as markdown with 3bmd, optionally specifying a return-spec if the first line starts with "=>".

Generating Documentation

Documentation isn't just about having a reference, but it's nice to integrate docstrings and separately-written material. Gendoc does this by processing all the parts into HTML and concatenating them into a single file (or stream).

Currently the following component types are understood:

Clearly there could be more; TOC generation would be neat, HTML would be trivial. Patches welcome.

Adding Component Types

New components types are trivial to add:

(defun my-processor (stream name args) ...) (gendoc:add-processor :my-processor 'my-processor) (gendoc (...) (:my-processor x y z))

NAME is the name the processor was called with (in this example, :my-processor), and ARGS is the cdr of the part specified ((x y z)).

You should output HTML to STREAM.


In your ASD file specify:

(eval-when (:compile-toplevel :load-toplevel :execute) (asdf:load-system :gendoc)) : (defsystem :my-system-docs :pathname PATHNAME-TO-DOCUMENTATION ...) (gendoc:define-gendoc-load-op :my-system-docs :my-docs-package 'generate-function)

When you (asdf:load :my-system-docs), it will call GENERATE-FUNCTION, which presumably calls GENDOC to generate documentation.

GENDOC can use the pathname of the system to look for the rest of your files, and place output there.

Note: This also defines OPERATION-DONE-P to NIL for the system you specify. You probably don't want to do this for the main system, or it will be reloaded everytime ASDF looks for it.


The following id attributes are generated and can be used as anchors:

Note: All ids (except for input files) are lowercase.


The following classes are defined in the resulting html and can be used with CSS:

Tip: to convert your symbols and lambda lists to lowercase, you can use the CSS property text-transform: lowercase;

Reference: GENDOC



Call FUNCTION when the component named NAME is encountered in the gendoc spec.



Define PERFORM and OPERATION-DONE-P for ASDF:LOAD-OP for the system SYSTEM-NAME, causing LOAD-OP to always call FUNCTION-SYMBOL in the package PACKAGE-NAME.

For this to be useful, the specified function should call GENDOC to actually generate documentation.

=> string or no values

Generate documentation based on PARTS. Each part is processed in order and the output is written to STREAM, or, if specified, OUTPUT-FILE is overwritten (:if-exists :supersede).

TITLE and CSS specify their HTML counterparts.

OUTPUT-SYSTEM and OUTPUT-COMPONENT may be specified; if so, they are consulted to set *DEFAULT-PATHNAME-DEFAULTS*, and files are read from and written to this location.

PATH may be specified instead or along with OUTPUT-SYSTEM and OUTPUT-COMPONENT; if both are specified, PATH overrides.