As of 24 September, 2012, Wikipedia showed 51 different non-lisp
document generators. On the same date, Cliki showed 18 lisp
documentation tools, I had found 2 more on quicklisp that were not
listed in Cliki and several others were proposed by members of various
mailing lists. Maybe I should write my own? No, instead, I decided to
compare the lisp documentation tools and put my opinionated comments here.
Some I could not get to work (either my own fault or bit rot has set
in, possibly due to changes in asdf). A couple failed initially but I
was able to debug and make a simple change to overcome the problem.
The fixes are noted along with the relevant error messages. The last
time anyone seemed to look at this issue was back in 2005:
See this discussion. This,then, is my probably biased comparison (and wish
list). Comments and corrections would be greatly appreciated.

Unlike document generation tools in other languages, e.g. Doxygen or
Sphinx which read source code files, almost all the extant lisp document generation progams do introspection on a running system. The only
programs that I am aware of that reads the source code is cldoc and qbook.
Regardless of the approach taken, they are all intended to help with
the problem of keeping the documentation in sync with the source code.
Even if the programmer is one of those types who doesn't provide
documentation strings in the code, these applications will at least
give you an api.

Some of these programs only provide the external api,
I'm referring to those as API-Generators. Others provide at least the
option for both the internal and external api. Those are set out in
the Full-Manual-Generators section. There are also the
Dynamic-Browsers, which may only be possible in lisp. They use a small
webserver backend and generate api documentation on the fly for any
packages currently loaded in your lisp image.

Time for a small rant. Of course, just having the names and parameters of
functions with no hint as to how it all fits together means that some
prospective user has to slog through your code to decide if it does
what they need. And if you wrote some clever code and did not provide
a roadmap, the prospective user is simply going to give up and write
their own version. If you want people to use your software, write up
some type of explanation and provide a simple example or two. There
is at least one package in the quicklisp loadable libraries where the
author actually stated that he decided to write his own graphics
routines rather than trying to figure out how to use a certain
existing graphics library. Communities do not grow unless you give
them a reason to come together. Having the greatest code in the world
is not sufficient to bring people together to want to use your code.
That starts with helping understand (a) how to use your code and (b)
why they should want to use your code.

1.2Overview

What you would look for in a documentation
tool is going to vary, depending on what you want to do.

If you are browsing through what is loaded in quicklisp, then you want a dynamic
webserver application that allows you to quickly look at all the
different packages currently loaded. So for that you would turn to
manifest or docbrowser. (Dynamic Browsers)

If you are looking to generate an api of the exported symbols only,
then you are looking at API Exporters such as atdoc, cl-api, or
gendoc. This type of output is obviously going to be simpler than the
full blown manuals for use by your internal development team.

There is the whole subject of literate programming, where you really are
interweaving the whole story of the whys and wherefores of the program
in with the source code and exporting (or "tangling") the source code
for compilation. For this purpose, you could look at clweb, LP/Lisp or
Org-mode's Babel ability.

Then there are packages that don't quite fit the above. In one corner is
Documentation-Template which creates a template that you are expected to
flesh out (if you are doing it right). In another corner is qbook
which pretty much just prints your source code in a nice format. A
third corner is occupied by defdoc with it's "semi-literate
programming approach".

Hopefully this review will give you a taste of what is available.
Note: I could only get document-template and lispdoc to
work after small editing changes.

The first thing that struck me in testing the packages was how
difficult this actually is. Running these tools against several
packages would trigger errors dealing with one package, warnings
against another and a third would generate documentation cleanly. I've
tried to include a sample of error messages and the packages that
generated them for all the documentation generation applications that
I could get working.

One thing I was disappointed in was how so few packages took advantage
of getting information from the asdf system. This is likely because so
few authors put the information in the asdf file. So, a plea to
all authors: please use that asd file fully. It allows for author,
maintainer, license (or licence), description and long-description.
This would help both documentation generation packages
and the entire quicklisp project. Then we can get at them
automatically rather than needing those input on the repl. E.g.

How do the lisp document generation programs compare to Doxygen or
Sphinx? So far I haven't seen the dependency visualizations that
Doxygen can create. See examples here. It is certainly possible to
generate these in lisp. See Ryan Davis' blog note
Visualizing call graphs in lisp using swank and graphviz. In the Python world, Sphinx
seems to create a framework that you are expected to complete by
writing reStructuredText documents. Example links can be
found here. Certainly cl-docutils gives you access to lisp tools for
reStructuredText.

I would be remiss if I did not mention http://www.lispdoc.com/. It is
not a documentation generator, but allows you to search various Common
Lisp documents and libraries for terms or symbols. albert and hyperdoc
are not part of the Summary tables below . They are, however,
discussed in their own sections below. I could not get
Albert to build. Hyperdoc is sufficiently different
that it does not fit well into the comparison.

1.3Wish-List

Author, Maintainer, Version, License, Generation Date
It is one thing if you are just browsing through the api to use
something for your own program, but I think that the package should
show author, maintainer (possibly more valuable than the author),
version, license and generation date information if available.

Multipage Generation
Some of the packages generate a single html page. Generating a 7 MB
html page may work for some people, but personally, something that big
should be broken into manageable pieces.
Indicate wish lists: e.g. clod needs to break things out into separate
pages. Error handling needs to indicate where in the program the error
was triggered.

Class inheritance
Report class inheritance items in an appendix?

Component Dependencies
Report on the component dependencies. Yes, this duplicates looking at
the asd file, but now you have it with the rest of the documentation
too.

Automatic incorporation of text pages
It would be nice to allow incorporation of external text pages,
anything from the typical README or TODO or COPYING or LICENSE to more
extended introductions, and more detailed discussion of the
application. Allowing incorporation of external text pages would also allow
incorporation of use examples into the documentation.

At this point, the only package that seems to do that is
gendoc.

Document Shadowing
It would be nice to flag whenever an application has to shadow another
package it is using.

Nice but merely trivia
The packages that generated html did not generate valid xhtml. Yes,
you could run tidy against each result, but it would be nice if the
code was cleaned up a little more.

It would be nice to generate an appendix page showing statistics on
the number of each type of symbol. Or lines of code or …. yes,
merely trivial stuff.

1.4 Description of Test Setup

Return to Top
Testing was done on sbcl version 1.0.58 running on (a) linux kernel
version 3.4.0 and (b) mac os snow leopard.

Several packages were tested. These included hunchentoot, postmodern,
cl-postgres, cl-who, the document generation packages themselves and
an additional test package consisting of 22 files with 1207 total
symbols, including 7 exported symbols (2 functions, 1 class, 2 macros,
1 generic function, 1 variable), As internal symbols, it has 7
classes, 41 variables, 16 generic functions, 24 macros and 417
internal functions. Did you notice that the numbers do not add up? I
believe those are unbound variables. So much for the trivia list for
statistics.

2Dynamic-browsers

After using these two packages for awhile, I found myself liking the cleaner index approach of manifest, but usually going to docbrowser because of the ability to click on the name of a function and immediately being shown the source code. Overall preference: docbrowser.

2.1docbrowser

Summary
Notes: This is a dynamic webserver based package, like Manifest,
generating only dynamic html. It only shows the exported symbols. Docbrowser has an issue with packages such as cl+ssl that have plus sign in the name.

Note that reloading the index page of all
packages currently loaded does not refresh, so if you have
subsequently loaded a package, it will not show up in the index list.
It will be accessible, however.

The webpage generated for a package shows tabs for functions, classes
and variables. The functions tab lists all exported functions, It will
note whether it is a function, a generic function, or macro, but there
is no separate index for each of those types.

Usage

(ql:quickload :docbrowser)(docbrowser:start-docserver 8084)

or whatever port you want to use. The default is 8080

Installation Notes

Generated Information

Generated Information

Author:

No

Author Email:

No

License Info:

No

Software Version:

No

Homepage:

No

Table of Contents:

No

Index:

Yes - Functions, Classes, Variables

Organization

Tabs for Functions, Classes, Variables

Designate Target Directory:

N/A

Multipage:

Only split by functions, classes and variables

Export Formats

Dynamic html

Show Dependencies:

No

Show Uses:

No

Show Used By:

No

Generation Date:

N/A

External Functions:

Yes (Show parameters)

Internal Functions:

No

Macros:

Flagged in the list of functions

Generic Functions:

Flagged in the list of functions. Clicking on the function name will take you to the source code page in the browser.

Class Info:

Yes, Slots, Specialized by

Slot Accessors:

Yes, in the list of slots in each class description

Special Variable Values:

Yes

Conditions:

Flagged in the list of functions

Package Info:

No

General Notes:

No

Installation Notes:

No

Markup Language:

No

Generate UMI:

No

Statistics:

No

What Calls What:

No

Interfaces with Unit Testing?

No

Flags Missing Functions:

No

Accept External File Input:

No

2.2manifest

Summary
Manifest shows the most complete set of different types of items, but
strangely does not show parameters. While
most packages satisfy themselves with exported functions, variables
and macros, Manifest provides additional information on generic
functions, slot accessors, classes, conditions, constants, used by and uses.

From the README file: Manifest is a system for semi-automatically
documenting Common Lisp packages. (A manifest tells you what's in a
package. Also this system makes manifest a bunch of information that
is actually present in a Lisp system.) The basic premise is that every
exported symbol in a package should be documented.

To check it out, after loading the system, evaluate (start) and point
your browser at the URL it returns.

Wish List

Link from each package page back to the index of packages.

Author, license, version information
Obviously, this is only to the extent possible. If the author did not
provide the information in the asd file, it will not be available.

Indexes

Usage

(ql:quickload :manifest)(manifest:START)

It will return a url with a localhost:portno. Just open your browser
to that portnumber: e.g. localhost:49434

Summary
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. As a result, you
really have to use the markup language in all your document strings in
order to get full use of the package.

Note that while atdoc has an argument for
including-internal-symbols-p, I could not get it to actually generate
pages for internal symbols.

Error Items
Mac Box: When trying to generate docs for postmodern, I got the following error
message:

There is no applicable method for the generic function
#<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)>
when called with arguments
(#<BUILT-IN-CLASS REAL>).
[Condition of type SIMPLE-ERROR]

Mac box: When trying to generate docs for hunchentoot, cl-who, I got the following
error message:

3.2cl-api

Summary
cl-api only generates the strings for the exported symbols. A single
page was generated for each package, with separate sections for
constants, variables, classes, functions, and macros. The html page
generated allows you to collapse each of those sections.

There is no applicable method for the generic function
#<STANDARD-GENERIC-FUNCTION SB-MOP:FINALIZE-INHERITANCE (5)>
when called with arguments
(#<BUILT-IN-CLASS REAL>).
[Condition of type SIMPLE-ERROR]

Summary
Description: This is a simple but flexible modular document generator
for Common Lisp. What I like about this one is its ability to import
other written documents, not just the document strings in the source code.

triggered error messages stating:
The bounding indices 0 and 1 are bad for a sequence of length 0.
[Condition of type SB-KERNEL:BOUNDING-INDICES-BAD-ERROR]

Fix per Pascal J. Bourguignon:actual bug is in: package-navigation-menuThis function generates a link for a parent package list, assuming hierarchical packages names with components separated by dots. For packages at the root (without dots in their names), it should not generate a parent link. The solution is to replace (when parent …)with (when parent-path …)

Yes Alphabetical Symbol and Permuted Symbol Indexes. Each index has its own page.

Organization

Alphabetical, with separate indexes

Designate Target Directory:

Yes

Multipage:

Separate Index pages only

Export Formats

html (not valid xhtml)

Show Dependencies:

No

Show Uses:

No

Show Used By:

No

Generation Date:

No

External Functions:

Yes (Shows parameters)

Internal Functions:

No

Macros:

Yes, Symbols which are macros are flagged as such

Generic Functions:

Yes Symbols which are generic are flagged as such

Class Info:

Yes, class precedence list and class init args

Slot Accessors:

No

Special Variable Values:

yes, shows initial values

Conditions:

Symbols which are conditions are flagged as such

Package Info:

No

General Notes:

No

Installation Notes:

No

Markup Language:

No

Generate UMI:

No

Statistics:

No

What Calls What:

No

Interfaces with Unit Testing?

No

Flags Missing Functions:

No

Accept External File Input:

No

A permuted index includes each n-word entry up to n times, at points
corresponding to the use of each word in the entry as the sort key.
For example, a symbol FOO-BAR would occur twice, once under FOO and
BAR. This allows you to use any word in th symbol's name to search for
that symbol.

4Full-Manual-Generators

The winner here is declt, in version 1.0b15, just by shere amount of information. It does not include other files, so you have to include tutorials or other documents manually, but neither do its competitors.

4.1cldoc

Summary
Cldoc calls asdf to find the source code, and then reads the source
code to pull the document strings rather than otherwise introspecting
into the system. The last revision in the version control system seem
to be in January 2006.

Installation Notes
First you need to get it. It does not have a quicklisp available
installation. You need to pull it from the cvs into your desired location.

The source code is now going to be in a cldor/src directory, so you
may want to move the source code to some location more in keeping
with your procedures and where your lisp expects to find new packages. Then:

Summary
Clod generates a single emacs org-mode file, which can be gigantic and
does take a substantial amount of time for org-mode in emacs to parse
and export. In fact, my midsized test package triggered out of space errors for
some regex function in org-mode when I tried to generate a pdf version
of the documentation. Running it on hunchentoot generated a 306k org
file with a resulting 736k xhtml file.

A lot of things have changed since the previous version, sometimes in a backward-incompatible way. Many more items are documented (including, as you have recently seen, method combinations). In addition to the reference manual, generated by Declt itself, there is now a real user manual.

Declt is SBCL-only, requires ASDF 3 and Texinfo 4 but generates code that is compatible with Texinfo 5. Also, beware, I've deleted the old repository and moved the project to GitHub. Below is a more precise description of what Declt currently does.

Declt (pronounce "dec'let") is a reference manual generator for Common Lisp libraries. It works by loading an ASDF system and introspecting its contents. The generated documentation contains the description for the system itself and its components (modules and files), the packages defined in that system and the definitions found in those packages.

Exported and internal definitions are listed separately. This allows the reader to have a quick view on the library's public API. Within each section, definitions are sorted lexicographically.

Reference manuals are generated in Texinfo format (compatible, but not requiring Texinfo 5). From there it is possible to produce readable / printable output in info, HTML, PDF, DVI and PostScript with tools such as makeinfo, texi2dvi or texi2pdf.

The Declt reference manual is the primary example of documentation generated by Declt itself.

Because declt generates texi files, you are required to use programs
like texi2pdf or texi2html to generate other formats.

In order to generate the document format you really want. Version
1.0b14 also provides a :DECLT-NOTICE keyword argument that gives you
control on the "automatically generated by Declt" notice that appears
in the reference manuals.

Installation Notes
No problems

Error Notes
I did have a couple of error messages running declt on hunchentoot and
cl-postgres. Those seem to be fixed in the version 1.0b14.

Generated Information

Generated Information

Author:

Yes You can specify them in the call to the document generator or it will default to what is in the system definition

Author Email:

Yes You can specify them in the call to the document generator or it will default to what is in the system definition

The system page gives the name, desription, dependencies (the only
program that shows dependencies), the source directory, and the
installation directory. I don't yet see a difference between the
source directory and the installation directory.

The modules page gives the name of separate modules in the package.
Each module has its own page which lists its location and its
component files.

The files page index lists the different files in the package. Each
separate page for each file shows the parent module, the location,
the exported definitions, the internal definitions, and links to
those. The link to the source code file location did not always work.

Each symbol lists the package and file that the source code is in.

Multipage: Yes*
Note that you are passing that argument to texi2html or text2pdf
outside of lisp. For example, texi2html –split node postmodern.texi

Export Formats: Texi
You then need to run other programs to convert from texi format
to your desired format (e.g. pdf, html, info). Note that some of those
conversion programs convert to html, but not valid xhtml

Show Dependencies: Yes
Declt is the only package to show dependencies. (Other packages show uses.)

Package Info: Yes
For example, the package info for postmodern noted both postmodern
and postmodern-system. Postmodern-system was noted as using
common-lisp and asdf. Postmodern was noted as using cl-postgres,
closer-common-lisp and s-sql.

4.5sb-texinfo

Summary
Converts docstrings for inclusion in a texinfo manual. The texinfo
manual can be edited prior to inclusion of the docstrings or
post-inclusion. It can then itself be exported to html, pdf or info formats.

Usage
To get the source

git clone git://github.com/nikodemus/sb-texinfo.git

Then create the includes and generate the base package for e.g., hunchentoot, with just
the docstrings:

4.6tinaa

Summary
With its indexes and table of contents, Tinaa is possibly the easiest
package in terms of actually finding things from the standpoint of
different categories of items. Tinaa has the second most complete set
of different types of items (second only to Manifest). While
most packages satisfy themselves with exported functions, variables
and macros, Tinaa provides additional information on generic
functions, slot accessors, classes, conditions and uses.

As a minor item of interest, Tinaa provides a count of the number of
total symbols and number of exported symbols, but does not break those
statistics down into the specific types of symbols.

Tinaa has a separate page for each symbol, with both table of contents
and separate indexes for class, conditions, variable, function, macro, symbol,
and permuted. Tinaa can show just external symbols or external and
internal symbols.

Tinaa does not note the name of the author, the license type or the
description of the package on the index page.

Yes The individual page for each function shows parameters. The parameters are not shown on the table of contents or index pages

Internal Functions:

Yes The individual page for each function shows parameters. The parameters are not shown on the table of contents or index pages

Macros:

Yes

Generic Functions:

Yes Shows the number of methods and the inputs for those methods

Class Info:

Yes default initargs, slots, direct method and other methods and whether it a metaclass for other classes

Slot Accessors:

Yes

Special Variable Values:

Yes

Conditions:

Yes. But not inherited conditions. See Below

Package Info:

No

General Notes:

No

Installation Notes:

No

Markup Language:

No

Generate UMI:

No

Statistics:

Yes - # Total Symbols, # External Symbols

What Calls What:

No

Interfaces with Unit Testing?

No

Flags Missing Functions:

No

Accept External File Input:

No

Index: Yes -
Indexes by Class, Variable, Function, Macro, Symbol and Permuted Symbol Indexes
A permuted index includes each n-word entry up to n times, at points
corresponding to the use of each word in the entry as the sort key.
For example, a symbol FOO-BAR would occur twice, once under FOO and
BAR. This allows you to use any word in th symbol's name to search for
that symbol.

Conditions: Yes - But not always
Tinaa did not show the database-connection-error, database-error or
sql-error in postmodern. It did show those errors in cl-postgres which
is used by postmodern.

5Literate-Programming

Return to Top
The simplest explanation of literate programming is that you start
with the explanation of what you are doing, inserting your code into
the explanation. Now you may have a great explanation of the program
and why you made your various coding decisions, but What are you
writing for? If you also need to export an api, then you need to a way
to export just the external symbols and docstrings. If you want to
export all the source code (what org-mode would call tangling), then
you need to make sure you can do that as well. See Appendix-2 for more
links to literate programming in general.

These programs help, but you are expected to write the documentation, not
auto-generate some documentation.