Lisp Documentation Generation Apps (version 0.3)

documentation-tools

1 Biased-review of documentation tools

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.

1.1 Lisp Documentation Generation Approaches

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.

Return to Top

1.2 Overview

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.

If you were looking to generate a full manual on a piece of software for internal use then you are looking at programs such as clod, declt, sb-texinfo or tinaa.

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.

(ignore-errors (asdf:system-author (asdf:find-system 'cl-api))) "Andrea Chiumenti"

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.3 Wish-List

Return to Top

  • 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?
  • 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.

2 Dynamic-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.

Return to Top

Dynamic Browsers

docbrowser manifest
Quicklisp x x
internal symbols
x
author

author email

license info

toc (2)

index(2) f,c,v
organization (2) f,c,v f,m,g,sa,v,cl,co
Designate Target directory

Multipage (3)

Export formats(4) dh dh
Errors in testing

Show dependencies

Show uses
x
Show used by

software version

Statistics

Generation Date

Class info (5) d,s,m d,s,m
Variable Values x
Conditions x(8) x
Own Markup language

Generate UMI

What calls what

Functions tested(6)

flag missing functions

Accept external file input(7)

Homepage docbrowser manifest

(2)

a -> alphabetical cl -> classes co -> conditions cs -> constants d -> definitions
f -> function fi -> files g -> generic functions i -> indexes m -> macros
me -> methods mo -> modules ot -> other types pa -> packages pe -> permutations
s -> system sa -> slot-accessors v -> variables

(3) is the html or xhtml generated in multiple pages or one giant page?

(4) h-> static html, l->latex, i->info, d->docbook,p->pdf,x->xhtml, dh -> dynamic html, texti

(5) d-> doc string, s-> slots, m-> direct methods sup-> superclasses, dsub-> documented subclasses, dia->default init args

(6) Is there any way to tie the documentation to a testing framework to see if every function has a test?

(7) Take text information from external files such as a text summary

(8) Shows conditions as functions in the function list. If it is a condition, macro, generic function, there will be a flag to that effect next to the name of the function.

(9) You can specify them in the call to the document generator or it will default to what is in the system definition.

(10) Single page with sections for constants, variables, classes, conditions, functions and macros which can be folded.

(11) The requirement of separate pages needs to be passed to a non-lisp program that manages the texi file. E.g., text2html –split node postmodern.texi

2.1 docbrowser

Return to Top Return to Summary Table

  • In Quicklisp: Yes
  • Author: Elias Martenson
  • Author Email
  • License Info: BSD-3 Clause
  • Software Version
  • 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.2 manifest

Return to Top Return to Summary Table

  • In Quicklisp: Yes
  • Author: Peter Seibel
  • Author Email
  • License Info: MIT?
  • Software Version
  • 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

  • Installation Notes
    Easy installation and running.
  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: No
    Index: No Organization Nickname, Functions, Macros, Generic Functions, Slot Accessors, Variables, Classes, Conditions, Uses
    Designate Target Directory: Dynamic Webpage Multipage: No
    Export Formats Dynamic Webpage Show Dependencies: No
    Show Uses: Yes Show Used By: Yes
    Generation Date: N/A

    External Functions: Yes (Does not show parameters) Internal Functions: Yes (Does not show parameters)
    Macros: Yes Generic Functions: Yes
    Class Info: Yes Slot Accessors: Yes
    Special Variable Values: No Conditions: Yes
    Package Info: No General Notes: No
    Installation Notes: N/A 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

    Return to Top

3 API-Generators

There really was no clear winner in the packages that just generated an api.

Return to Top

API Generators

atdoc cl-api gendoc lispdoc
Quicklisp x x x (cl-gendoc)
internal symbols



author



author email



license info



toc (2)
(10)

index(2)


a,pe
organization (2)
cs,v,cl,co,f,m v,f,m a,i,pe
Designate Target directory
x
x
Multipage (3) x

(12)
Export formats(4) h,p,i h h h
Errors in testing x x

Show dependencies



Show uses



Show used by



software version



Statistics



Generation Date



Class info (5) d,s,sup,dsub d,s,sup,dia
d,sup,dia
Variable Values
x
x
Conditions
x
x
Own Markup language x


Generate UMI



What calls what



Functions tested(6)



flag missing functions



Accept external file input(7)

x
Homepage atdoc cl-api gendoc lispdoc
(2)
a -> alphabetical cl -> classes co -> conditions cs -> constants d -> definitions
f -> function fi -> files g -> generic functions i -> indexes m -> macros
me -> methods mo -> modules ot -> other types pa -> packages pe -> permutations
s -> system sa -> slot-accessors v -> variables

(3) is the html or xhtml generated in multiple pages or one giant page?

(4) h-> static html, l->latex, i->info, d->docbook,p->pdf,x->xhtml, dh -> dynamic html, texti

(5) d-> doc string, s-> slots, m-> direct methods, sup-> superclasses, dsub-> documented subclasses, dia->default init args

(6) Is there any way to tie the documentation to a testing framework to see if every function has a test?

(7) Take text information from external files such as a text summary

(8) Shows conditions as functions in the function list. If it is a condition, macro, generic function, there will be a flag to that effect next to the name of the function.

(9) You can specify them in the call to the document generator or it will default to what is in the system definition.

(10) Single page with sections for constants, variables, classes, conditions, functions and macros which can be folded.

(11) The requirement of separate pages needs to be passed to a non-lisp program that manages the texi file. E.g., text2html –split node postmodern.texi

(12) Indexes are separate pages

3.1 atdoc

Return to Top Return to API Generator Summary Table

  • In Quicklisp: Yes
  • Author: David Lichteblau
  • Author Email: david@lichteblau.com
  • License Info: X11 Style
  • Software Version
  • 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.

  • Usage
    (ql:quickload :atdoc) (atdoc:generate-html-documentation '(:document-test1) "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/" :index-title "Test Doc1 ATDOC" :heading "Test Doc1 ATDOC" :single-page-p nil :include-internal-symbols-p t) (atdoc:generate-html-documentation '(:document-test1) "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/" :include-internal-symbols-p t :heading "ATDOC Documentation Generator Test" :index-title "Documentation Generator Test Index" :single-page-p nil :include-slot-definitions-p t)

    Note the above did not generate the non-exported symbols

    NOTE ATDOC for latex and info did not allow the above keywords

    (atdoc:generate-latex-documentation '(:document-test1) "/home/sabra/quicklisp/local-projects/document-test1/docs/atdoc/" :include-slot-definitions-p t)
  • Installation Notes
  • 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:

    Evaluation aborted on #<SIMPLE-ERROR "unexpected closing brace" {1002EA0863}>

    Running atdoc against tinaa generated the following warning:

    WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: No
    Index: Yes Index is alphabetical, noting whether the exported symbol is a variable, class for function. Flags undocumented functions in red Organization
    Designate Target Directory: Yes Multipage: Yes
    Export Formats html,tex,info Show Dependencies: No
    Show Uses: No Show Used By: No
    Generation Date: No

    External Functions: Yes (Show parameters) Internal Functions: No
    Macros: No Generic Functions: No
    Class Info: Superclass, documented subclasses, slots Slot Accessors: Yes
    Special Variable Values: No Conditions: No
    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

    Note. This generates valid html, not valid xhtml.

3.2 cl-api

Return to Top Return to API Generator Summary Table

  • In Quicklisp :Yes
  • Author: Andrea Chiumenti
  • Author Email
  • License Info: BSD
  • Software Version
  • 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.
  • Usage
    (ql:quickload :cl-api) (cl-api:api-gen :document-test1 #P"/home/sabra/quicklisp/local-projects/document-test1/docs/cl-api/") Generation complete: "/home/sabra/quicklisp/local-projects/document-test1/docs/cl-api/document-test1.html"
  • Installation Notes
  • Error Messages:
    On my mac box, running cl-api against postmodern generated 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]

    Running it against cl-postgres generated the following warning:

    WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: No (Collapsible Sections on a single html page)
    Index: No Organization Constants, Variables, Classes, Conditions, Functions, Macros
    Designate Target Directory: Yes Multipage: No
    Export Formats html (not valid xhtml) Show Dependencies: No
    Show Uses: No Show Used By: No
    Generation Date: No

    External Functions: Yes (Show parameters) Internal Functions: No
    Macros: Yes Generic Functions: Functions flagged as generic
    Class Info: parent class, Default initargs, slots, the docstring for the class. Slot Accessors: Yes
    Special Variable Values: Yes Conditions: Yes
    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

3.3 gendoc

Return to Top Return to API Generator Summary Table (AKA cl-gendoc)

  • In Quicklisp: Yes
  • Author : Ryan Pavlik
  • Author Email
  • License Info: LLGPL, BSD
  • Software Version: 1.0
  • 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.
  • Usage
    (ql:quickload :cl-gendoc) (gendoc (:output-filename "docs.html" :css "simple.css") (:mdf "intro.md") (:mdf "details.md") (:apiref :some-package :another-package) (:mdf "closing.md")) (gendoc:gendoc (:output-filename "/Users/sabra/data/lisp/document-tools/docs/gendoc/gendocs-postmodern.html" :css "simple.css") (:apiref :postmodern))
  • Installation Notes
  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: No
    Index: No Organization Special Variables, Functions, Macros
    Designate Target Directory: Yes Multipage: No
    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, if external Generic Functions: No
    Class Info: No Slot Accessors: No
    Special Variable Values: No Conditions: No
    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: Yes

3.4 lispdoc

Return to Top Return to API Generator Summary Table

  • In Quicklisp: No
  • Author: Sven Van Caekenberghe, Pascal J. Bourguignon
  • Author Email
  • License Info: LLGPL
  • Software Version
  • Summary
    Tested: Yes

    lispdoc generates html documentation for exported symbols based on their documentation strings. It is not included in Quicklisp but Pascal Bourguignon pointed me to his fork.

    I did have to make one editing change, noted below, in order for it to run against all my test packages.

  • Usage
    Unable to run against several applications without a modification
    (lispdoc-html "/home/sabra/projects/lisp-doc/document-tools/docs/lispdoc/" (list 'hunchentoot) :title "Hunchentoot")
  • Error Notes
    Trying to run against postmodern, hunchentoot and several other packages using the following call
    (lispdoc-html "/home/sabra/projects/lisp-doc/document-tools/docs/lispdoc/" (list 'hunchentoot) :title "Hunchentoot")

    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-menu
      This 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 …)

      (when parent-path
        (list (list parent (format nil "Up: ~A" (shorten parent)))))
  • 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 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.

4 Full-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. 
Full Manual Generators

cldoc clod declt document-template sb-texinfo tinaa
Quicklisp
x x x
x
internal symbols x x x

x
author

x (9)


author email

x (9)


license info

x (1)


toc (2) fi,i cl,cs,v,m,f s,mo,fi,pa,d,i a a,f,v,ot
index(2) a
f,v,cl
fi,v,ot cl,v,f,m,s,pe,co
organization (2) fi,cl,me,f,m
s,mo,f,pa,d,i a a,fi,v,ot cl,v,f,m,s,pe,co
Designate Target directory x x x x x x
Multipage (3) x
x (11)

x
Export formats(4) h orgmode texi h texi h
Errors in testing (15)

(8)
x
Show dependencies

x


Show uses
x x


x
Show used by
x x



software version

x


Statistics




x
Generation Date x x x x
x
Class info (5) d,s,m,sup,dia d,s,m,sup,dsub,dia d,s,m,sup,dia
x (13) d,s,sup,dia d,s,m
Variable Values
x



Conditions

x x (13) x x
Own Markup language



texinfo
Generate UMI





What calls what





Functions tested (6)





flag missing functions





Accept external file input (7)





Homepage cldoc clod declt document-template sb-texinfo tinaa
Other



(14)

(1) Declt version 1.0b14 has license terms for BSD, GPL, MIT and LLGPL.

(2)

a -> alphabetical cl -> classes co -> conditions cs -> constants d -> definitions
f -> function fi -> files g -> generic functions i -> indexes m -> macros
me -> methods mo -> modules ot -> other types pa -> packages pe -> permutations
s -> system sa -> slot-accessors v -> variables

(3) is the html or xhtml generated in multiple pages or one giant page?

(4) h-> static html, l->latex, i->info, d->docbook,p->pdf,x->xhtml, dh -> dynamic html, texti

(5) d-> doc string, s-> slots, m-> direct methods sup-> superclasses, dsub-> documented subclasses dia->default init args

(6) Is there any way to tie the documentation to a testing framework to see if every function has a test?

(7) Take text information from external files such as a text summary.

(8) Required a minor change to the source code, see installation notes.

(9) You can specify them in the call to the document generator or it will default to what is in the system definition.

(10) Single page with sections for constants, variables, classes, conditions, functions and macros which can be folded.

(11) The requirement of separate pages needs to be passed to a non-lisp program that manages the texi file. E.g., text2html –split node postmodern.texi

(12) Declt only provides limited information here. It only provides the name and the document string, unlike other packages which provide slots, methods, etc.

(13) Symbols which are classes or conditions are noted as such. Any additional information must be input manually.

(14) sbcl specific.

(15) Error on unbound variable in hunchentoot

4.1 cldoc

Return to Top Return to Summary Table

  • In Quicklisp: No
  • Author: Iban Hatchondo
  • Author Email:
  • License Info: LLGPL
  • Software Version: 2005
  • 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.
    cvs -z3 -d :pserver:anonymous:anonymous@common-lisp.net:/project/cldoc/cvsroot co .
    

    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:

  • Usage
    (ql:quickload :cldoc)
    
    (cldoc:extract-documentation 
          'cludg:html 
          "/home/sabra/projects/lisp-doc/document-tools/docs/cldoc/" 
         (asdf:find-system :hunchentoot) 
          :table-of-contents-title "Hunchentoot by Cldoc")
    
    Notice the asdf:find-system call.

    Unfortunately, running it against hunchentoot generates an error message about The variable http-moved-temporarily is unbound. [Condition of type unbound-variable]

    On the other hand, running it against postmodern was successful.

    (cldoc:extract-documentation 'cludg:html "/home/sabra/projects/lisp-doc/document-tools/docs/cldoc/" (asdf:find-system :postmodern) :table-of-contents-title "Postmodern by Cldoc")

    This will generate an index.html file which lists separate html files for each source code file and an alphabetical index.

  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: Yes, name of source-code files
    Index: alphabetical Organization file,class,method,function,macro
    Designate Target Directory: Yes Multipage: Yes
    Export Formats html (See below) Show Dependencies: No
    Show Uses: No Show Used By: No
    Generation Date: Yes

    External Functions: Yes, but not noted as external Internal Functions: Yes but not noted as internal
    Macros: Yes (shows params) Generic Functions: Yes, flagged as generic, methods are explicitly set out separately
    Class Info: Parents, initarg,accessors Slot Accessors: Yes, in class summary
    Special Variable Values: Name only Conditions: No
    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
    • Export Formats
      The generated html would have been good xhtml 1.0 Strict except for Missing xmlns attribute for element html. The value should be: http://www.w3.org/1999/xhtml

4.2 clod

Return to Top Return to Summary Table

  • In Quicklisp
  • Author
  • Author Email
  • License Info
  • Software Version
  • 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.
  • Usage
    (clod:DOCUMENT-PACKAGE 'hunchentoot "/home/sabra/projects/lisp-doc/document-tools/docs/clod/hunchentoot.org")
  • Installation Notes
    Note: Clod did not load on my macbook. It did load on my linux box.
  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: class,variable,macro,functions
    Index: No Organization External classes,constants, variables,macros,functions,internal classes, constants,variables,macros,functions,alphabetical index
    Designate Target Directory:
    Multipage: No
    Export Formats org-mode Show Dependencies: No
    Show Uses: Yes Show Used By: Yes
    Generation Date: Yes

    External Functions: Yes (Shows parameters) Internal Functions: Yes
    Macros: Yes Generic Functions: Yes
    Class Info: parent, precedence list,direct subclasses, description, direct slots, indirect slots, Slot Accessors: initial value, initargs
    Special Variable Values: Yes Conditions: Not noted 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

4.3 declt

Return to Top [[Full-Manual-Generators][Return to Summary Table]

  • In Quicklisp: Yes
  • Author: Didier Verna
  • Author Email
  • License Info: GPL
  • Software Version
  • Summary

    Declt has now made it to 1.0 release.

    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.

    In addition to ASDF system components and packages, Declt documents the following definitions: constants, special variables, symbol macros, macros, setf expanders, compiler macros, functions (including setf ones), generic functions and methods (including setf ones), method combinations, conditions, structures, classes and types.

    The generated documentation includes every possible bit of information that introspecting can provide: documentation strings, lambda lists (including qualifiers and specializers where appropriate), slots (including type, allocation and initialization arguments), definition source file etc.

    Every documented item provides a full set of cross-references to related items: ASDF component dependencies, parents and children, classes direct methods, super and subclasses, slot readers and writers, setf expanders access and update functions etc.

    Finally, Declt produces exhaustive and multiple-entry indexes for every documented item.

    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.

  • Usage
    (ql:quickload :com.dvlsoft.declt) (com.dvlsoft.declt:declt 'postmodern :VERSION "201209091" :AUTHOR "Marijn Haverbeke" :EMAIL "marijnh@gmail.com" :TEXI-FILE "/Users/sabra/data/lisp/document-tools/docs/declt/postmodern.texi")

    You would then need to run something else such as:

    texi2html --split node postmodern.texi

    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
    License Info: Yes if defined in the call to declt. :BSD :GPL :MIT :LGPL Software Version: Yes, but must be explicitly stated
    Homepage: No Table of Contents: System, Module, Files, Packages, Definitions, and Indexes
    Index: Yes Organization See below
    Designate Target Directory: Yes Multipage: Yes, See Below
    Export Formats Texi. See Below Show Dependencies: Yes
    Show Uses: No Show Used By: No
    Generation Date: Yes

    External Functions: Yes (Shows parameters) states package and source code filename Internal Functions: Yes (Shows parameters) states package and source code filename
    Macros: Yes (Shows parameters) states package and source code filename Generic Functions: Yes (Shows parameters) states package and source code filename
    Class Info: Limited states package and source code filename Slot Accessors: Yes documented as generic functions
    Special Variable Values: Yes to names, no to values Conditions: Yes, They are indexed in the Data Types Section
    Package Info: Yes General Notes: No
    Installation Notes: No Markup Language: No, but being worked on
    Generate UMI: No Statistics: No
    What Calls What: No Interfaces with Unit Testing? No
    Flags Missing Functions: No Accept External File Input: No
    • Organization:
      System, Modules, Files, Packages, Definitions and several index

      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.4 documentation-template

Return to Top Return to Summary Table

  • In Quicklisp: Yes
  • Author: Dr. Edmund Weitz
  • Author Email
  • License Info :BSD
  • Software Version
  • Summary
    Tested: Failed. However, manually going into document-template/output.lisp and changing "escape-string-iso-8859" to "cl-who:escape-string-iso-8859-1" fixed the initial problem.
  • Usage
    (ql:quickload :documentation-template) (documentation-template:create-template 'document-test1 :target #p"/home/sabra/quicklisp/local-projects/document-test1/docs/documentation-template/document-test1.xhtml" :subtitle "Document Tool Testing" )

    throws an error about: The function DOCUMENTATION-TEMPLATE::ESCAPE-STRING-ISO-8859 is undefined.

    As noted in the summary, this can be fixed, but preferably should be fixed upstream.

  • Installation Notes
    Required Editing to the source code: Manually go into document-template/output.lisp and change "escape-string-iso-8859" to "cl-who:escape-string-iso-8859-1".
  • Generated Information
    If you have seen Dr. Weitz documentation, you know what this looks like.
    Generated Information
    Author: No Author Email: No
    License Info: Defaults to BSD. You must edit Software Version: Defaults to 0.1 You must edit
    Homepage: Defaults to Dr. Weitz page. You must edit. Table of Contents: Yes (Alphabetical listing of all symbols)
    Index: No Organization Basically a dictionary of all symbols in the package
    Designate Target Directory: Yes Multipage: No
    Export Formats single page html (not valid xhtml) Show Dependencies: No
    Show Uses: No Show Used By: No
    Generation Date: Yes

    External Functions: Yes (Shows parameters) Not broken out from rest of symbol list. No indication of external or internal Internal Functions: Yes (Shows parameters) Not broken out from rest of symbol list. No indication of external or internal
    Macros: Yes Not broken out from rest of symbol list. No indication of external or internal Generic Functions: Yes Generic functions names and document strings are followed by the defined methods for that generic function and their specified argument types.
    Class Info: Partly Symbols in the symbol list which are classes are noted as such, but it does not indicate slots, accessors or other items connected to that class. Slot Accessors: No. Accessors to conditions are noted, but not accessors to classes
    Special Variable Values: Names yes, values no Conditions: Yes, but just with all the other 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

4.5 sb-texinfo

Return to Top Return to Summary Table

  • In Quicklisp: No
  • Author: Nikodemus Siivola
  • Author Email
  • License Info
  • Software Version
  • 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:

    (generate-includes "/home/sabra/quicklisp/local-projects/sb-texinfo/doc/include/" (list :hunchentoot) :base-package :hunchentoot) (document-package :hunchentoot :output-file "/home/sabra/quicklisp/local-projects/sb-texinfo/doc/hunchentoot.texinfo")

    Make sure that the style.css file is where you want it, then run your favorite texi export programs. E.g.

    makeinfo --html --no-split --css-include=style.css makeinfo --no-split huchentoot.texinfo texi2dvi hunchentoot.texinfo pdftex hunchentoot.texinfo
  • Installation Notes
  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: Introduction, Dictionary, Function Index, Variable Index, Type Index
    Index: Function Index, Variable Index, Type Index Organization Introduction, Dictionary, Function Index, Variable Index, Type Index
    Designate Target Directory: Yes Multipage: Depends on conversion program used from texinfo
    Export Formats texinfo. See below Show Dependencies: No
    Show Uses: No Show Used By: No
    Generation Date: No

    External Functions: Yes (Shows parameters) no indication as to what function is internal and what function is external Internal Functions: Yes (Shows parameters) no indication as to what function is internal and what function is external
    Macros: Yes Macros are labeled as such, but simply included with the other functions and methods Generic Functions: Yes labeled as such, but simply included with the other functions and methods
    Class Info: class precedence list, slots, docstrings Slot Accessors: Yes
    Special Variable Values: Names only Conditions: Yes Conditions are labeled but not broken out separately other than as a listing in the Type Index together with classes.
    Package Info: No General Notes: Only what is in the asdf file
    Installation Notes: No Markup Language: Texinfo
    Generate UMI: No Statistics: No
    What Calls What: No Interfaces with Unit Testing? No
    Flags Missing Functions: No Accept External File Input: No
    • Export Formats: texinfo
      Texinfo can be converted into other formats, e.g. pdf, html. Note that some of the conversion tools generate valid html but not valid xhtml.

4.6 tinaa

Return to Top Return to Summary Table

  • In Quicklisp: Yes
  • Author: Gary Warren King
  • Author Email: gwking@metabang.com
  • License Info: MIT
  • Software Version
  • 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.

    • Wish List
      • Specify Author, license, version information.
      • Accept additional text files and a user-specified css file.
      • Show which packages use this package (used-by)
  • Usage
    (ql:quickload :tinaa) (tinaa:document-system 'package 'document-test1 "/path/to/desired/directory/")
  • Installation Notes
  • Error Messages
    Running Tinaa against cl-postgres generated the following warning:

    WARNING: unsupported DOCUMENTATION: type T for object of type SB-PCL::CONDITION-DIRECT-SLOT-DEFINITION

  • Generated Information
    Generated Information
    Author: No Author Email: No
    License Info: No Software Version: No
    Homepage: No Table of Contents: Yes
    Index: Class, Variable, Function, Macro, Symbol, Permuted Organization Class, Variable, Function, Macro
    Designate Target Directory: Yes Multipage: No
    Export Formats html (not valid xhtml) Show Dependencies: No
    Show Uses: Yes Show Used By: No
    Generation Date: Yes

    External Functions: 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.

5 Literate-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.

Literate Programming

clweb LP/Lisp defdoc org-mode
Quicklisp



Homepage Clweb LP/Lisp defdoc

5.1 clweb

Return to Top Return to Summary Table

  • Author: Alex Plotnick

5.3 Semi-literate programming with defdoc

Subpages (1): lisp-generation-apps-v1
Comments