Staple

Nicolas Hafner <shinmera@tymoon.eu>

1.1.0
A tool to generate documentation about Lisp projects through an HTML tem-
plate.

About Staple

Staple is yet another Common Lisp documentation generation application. It uses

Clip and lQuery to do most of the work. The main features include automatic
package symbol index processing, documentation gathering from related files
and generation through expressive templates.

How To

Load Staple through ASDF or Quicklisp:

(ql:quickload :staple)
Generating documentation is a single command away:
(staple:generate :my-asdf-system)
This should create an about.html file within the source directory of the asdf-
system you specified. By default staple uses the same name as the asdf system

1
for the package index, but you may specify your package/s directly too if they
differ using the :PACKAGES argument.
Staple automatically searches your source directory for documentation files (like
README.md) to include into the finished file. You may however specify your
own file or a string directly with the :DOCUMENTATION argument. Staple currently
only parses Markdown files to HTML, but you may extend it with other formats
by adding a parse-documentation-file method.
The template used to generate everything is a Clip document. Understanding
how it works and throwing together your custom layout to use should not be
hard. For a full understanding of the system however please read the Clip
documentation.

Extending Staple

Staple can be extended to handle other “symbol types” and to automatically

behave different for specific systems. In order to do so you should create a
staple.ext.lisp file within the root source directory of the system you want to
have extensions for. This file will automatically be loaded when you generate
documentation for your system.
In order to add a new type of symbol, you should subclass one of the symb classes.
Depending on what kind of thing your type of symbol is, different classes may be
appropriate. You should then add methods that specialise on your subclass to
at least symb-documentation and symb-type-order. There are other methods
that give you more fine-grained control over how the symbols are represented.
Finally you’ll need to tell Staple how to find your new type of symbol when
it scans over packages. To do so, you should use define-converter or
define-simple-converter. Converters are functions that take a symbol and a
package, and return a list of symb objects that apply for the given symbol and
package combination.
This is all it takes for Staple to produce new symbol types in the index.
If you want to customise the default arguments to generate, or add additional
properties for usage in the template document, you can add a method to
system-options that specifies these properties.
(defmethod staple:system-options append ((system (eql (asdf:find-system :my-sys))))
(list :template (system-relative-pathname system \"my-clip-template.ctml\")
:if-exists :supersede))
See the documentation of system-options for the default properties that Staple
understands and supplies.
In general the staple.ext.lisp should allow you to lay down all the customi-
sation of your system so that all you’ll ever need to do to actually generate the

2
docs is
(ql:quickload ’(staple my-system))
(staple:generate :my-system)
and Staple will figure out everything automatically.

Documentation Browser

Staple includes a server so that you can view the documentation and symbol
index of all available ASDF systems on the fly.
(ql:quickload :staple-server)
(staple-server:start)
Depending on how many systems you have loaded, starting the server may take
a while as it produces a cache of all documentation pages. Once it’s done, visit
the url in the message. If you change the systems and want to view the updated
documentation, use staple-server:recache.

Copyright

staple is licensed under the Artistic license.

c Nicolas Hafner <shin-
mera@tymoon.eu> . This library can be obtained on https://github.com/
Shinmera/staple.

Package Index

STAPLE (ORG.TYMOONNEXT.STAPLE)

– special

*DEFAULT-TEMPLATE*
Pathname to the default template to use in GENERATE.
special

3
 *DOCUMENTATION-NAMES*
– A list of strings denoting common file names (without extension) for documentation
If you have your own file name, push it onto this list.

See *DOCUMENTATION-TYPES*
See FIND-DOCUMENTATION-FILE
– special

*DOCUMENTATION-TYPES*
A list of strings denoting common file types/extensions for documentation files.
If you have your own file type, push it onto this list.

See *DOCUMENTATION-NAMES*
See FIND-DOCUMENTATION-FILE
special

*EXTENSION-FILE*
– Pathname describing the filename for Staple extension files.
– special

*LEGACY-TEMPLATE*
Pathname to a rather plain and simple preset template that was used before the mode
special

*LOGO-NAMES*
– A list of strings denoting commong file names (without extension) for logos.
If you have your own file name, push it onto this list.

See *LOGO-TYPES*
See FIND-LOGO-FILE
– special

*LOGO-TYPES*
A list of strings denoting commong image types/extensions for logos.
If you have your own file type, push it onto this list.

See *LOGO-NAMES*

4
 See FIND-LOGO-FILE
special

*MODERN-TEMPLATE*
– Pathname to a simple, yet modern preset template.
– class

SYMB-ACCESSOR
Object representing an accessor.
class

SYMB-CLASS
– Object representing a class.
– class

SYMB-CONDITION
Object representing a condition.
class

SYMB-CONSTANT
– Object representing a constant.
– class

SYMB-FUNCTION
Object representing a function.
class

SYMB-GENERIC
– Object representing a generic function.
– class

5
 SYMB-MACRO
Object representing a macro.
class

SYMB-METHOD
– Object representing a generic function method.
– class

SYMB-OBJECT
Base class for symbol representation.
class

SYMB-SPECIAL
– Object representing a special variable.
– class

SYMB-STRUCTURE
Object representing a structure.
class

SYMB-TYPE
– Object representing a type.
– class

SYMB-VARIABLE
Object representing a variable.
accessor (

CONVERTER
NAME)
– Accessor to the converter function associated with the name.
Each converter function takes two arguments, a symbol and a package,
and must return a list of symb-object instances.

6
– accessor (

SYMB-METHOD
OBJECT)
No docstring provided.
– accessor (

SYMB-PACKAGE
SYMB-OBJECT)
Returns the symbol-package of the symbol.
accessor (

SYMB-SYMBOL
OBJECT)
– Returns the actual symbol backed by the symbol object.
– accessor (

SYSTEM-PACKAGES
SYSTEM)
Accessor to the list of packages associated to the system.

If the loading process of the system happened before staple was loaded, a
heuristic is used where a package name is returned that corresponds to the
system’s name. If the system was loaded after staple, this should return
the precise list of packages that the system defined.

If no corresponding package name could be found, an error is signalled.

See *SYSTEM-PACKAGES*
function (

ANCHOR
OBJECT)
– Returns a href-anchor.
– function (

7
 DAY
)
Return the current day of the month
function (

FIND-DOCUMENTATION-FILE
ASDF)
– Attempts to find a documentation file in the given asdf system’s source directory.
This relies on *DOCUMENTATION-NAMES* and *DOCUMENTATION-TYPES* to find an appropria

See *DOCUMENTATION-NAMES*
See *DOCUMENTATION-TYPES*
– function (

FIND-LOGO-FILE
ASDF)
Attempts to find a logo file in the given asdf system’s source directory.
See *LOGO-NAMES* and *LOGO-TYPES*. The system will also try to find files by
prepending or appending the system name to the logo names.

See *LOGO-NAMES*
See *LOGO-TYPES*
function (

GENERATE
ASDF-SYSTEM &REST ARGS &KEY COMPACT DOCUMENTATION
EXTENSION LOGO NAME OUT PACKAGES TEMPLATE IF-EXISTS
&ALLOW-OTHER-KEYS)
– Generates documentation for the given asdf-system.

If the system is not already loaded, it is loaded.

If there is an extension file within the system’s root
directory, that file is also loaded. The extension files
of the transitive dependencies of the system are
loaded as well, before that of your specified system.
This ensures that potential symbol classes they may
provide are also available to your system. For this to
work however, the transitive systems must use the default

8
 location for their extension files.

The system may specify default arguments in its options.

The arguments specified for GENERATE will always override
those, however. The arguments’ effects are explained in
SYSTEM-OPTIONS.

See SYSTEM-OPTIONS
See *EXTENSION-FILE*
– function (

LICENSELINK
LICENSE)
Returns an A tag linked to a TLDRLegal.com search on the license name.
function (

MONTH
)
– Return the current month
– function (

PACKAGE-SYMBOL-OBJECTS
PACKAGE)
Gathers all possible symbol-objects of the given package.
function (

PACKAGE-SYMBOLS
PACKAGE)
– Gets all symbols within a package.
– function (

PREPARE-DOCUMENTATION
SYSTEM DOC)

9
 Attempts to prepare the documentation for the given system.
In the case of a pathname, PARSE-DOCUMENTATION-FILE is called.
If the doc is NIL, a matching documentation file is attempted to be found through
FIND-DOCUMENTATION-FILE. If nothing is foudn for that as well, an empty string is
returned instead.
function (

REMOVE-CONVERTER
NAME)
– Remove the named converter.

See CONVERTER
– function (

RENDER-DOCSTRING-MARKDOWN
STRING)
Renders the docstring as a markdown highlighted string.
function (

RENDER-DOCSTRING-SEE-ALSO
STRING)
– Renders the docstring plainly, turning ’See X’ lines into links.
– function (

RESOLVE-SYMBOL-DOCUMENTATION
SYMBOL)
Attempts to resolve the (string) symbol to either an URL or an anchor.
This works by first testing against the package. If it is known (such as the
sb-*, mop, cl and *current-packages*) a link/anchor is returned. If nothing
can be found, NIL is returned instead. If no package designator is given,
the symbol is attempted to be automatically found in either the
*current-packages* or in CL.
function (

10
 STAPLE
IN &KEY (OUT (TO-OUT IN)) (IF-EXISTS :SUPERSEDE) CLIP-ARGS
(COMPACT T))
– Performs stapling actions/clip processing on the IN document.

IN is parsed by PLUMP:PARSE and the results are written to OUT.

Through CLIP-ARGS additional arguments can be passed to CLIP:GENERATE.
These will also appear in the *ROOT-CLIPBOARD*.
– function (

STEXT
NODE OBJECT)
Same as lQuery’s TEXT, but calls PRINC-TO-STRING on the object or uses an empty str
function (

SYMB-TYPE<
A B)
– Used to sort symbols alphabetically, grouped by their type.
– function (

SYMBOL-CLASS-P
SYMBOL)
Returns T if the symbol is a class.
function (

SYMBOL-CONDITION-P
SYMBOL)
– Returns T if the symbol is a condition.
– function (

SYMBOL-CONSTANT-P
SYMBOL)
Returns T if the symbol is a constant.
function (

11
 SYMBOL-FUNCTION-P
SYMBOL)
– Returns T if the symbol is a pure function.
– function (

SYMBOL-GENERIC-P
SYMBOL)
Returns T if the symbol is a generic function.
function (

SYMBOL-OBJECTS
SYMBOLS &OPTIONAL PACKAGE)
– Gathers all possible symbol-objects out of the list of passed symbols.
– function (

SYMBOL-SETF-FUNCTION-P
SYMBOL)
Returns T if the symbol is a setf function.
function (

SYMBOL-STRUCTURE-P
SYMBOL)
– Returns T if the symbol is a structure.
– function (

TO-OUT
PATHNAME)
Returns a pathname whose file-name (not extension) is postfixed by .out .
function (

12
 YEAR
)
– Return the current year
– generic (

PARSE-DOCUMENTATION-FILE
TYPE STREAM)
Used to perform special parsing on certain documentation files (such as Markdown).
The type should be an EQL-specializer to a keyword of the file-type/extension.

By default only .md files are specially handled, everything else is simply read as
generic (

RENDER-DOCSTRING
STRING SYSTEM)
– Render the docstring appropriately for the given system.

See RENDER-DOCSTRING-SEE-ALSO
See RENDER-DOCSTRING-MARKDOWN
– generic (

SYMB-ARGUMENTS
SYMB-OBJECT)
Returns the arguments of the function or NIL.
generic (

SYMB-DOCUMENTATION
SYMB-OBJECT)
– Returns the documentation-string.
– generic (

13
 SYMB-FUNCTION
SYMB-OBJECT)
Returns the symbol-function of the symbol.
generic (

SYMB-ID
SYMB-OBJECT)
– Returns a string representing the symbol uniquely.
– generic (

SYMB-NAME
SYMB-OBJECT)
Returns the symbol-name of the symbol.
generic (

SYMB-QUALIFIERS
SYMB-OBJECT)
– Returns the qualifiers of the method or NIL.
– generic (

SYMB-SCOPE
SYMB-OBJECT)
Returns whether the symbol is :INHERITED, :EXTERNAL or :INTERNAL.
generic (

SYMB-TRUE-SYMBOL
SYMB-OBJECT)
– Returns the the true symbol of the symbol.
Preferable over SYMB-SYMBOL as it takes SETF-function names into account.
– generic (

14
 SYMB-TYPE
SYMB-OBJECT)
Returns the string-name of the kind of object it represents.
generic (

SYMB-TYPE-ORDER
SYMB)
– For a given symbol type name, returns an integer representing the priority of the t
– generic (

SYMB<
A B)
Used to sort symbols alphabetically.
Special treatment is done so that generic functions should
always appear before their methods.
generic (

SYSTEM-OPTIONS
SYSTEM)
– Returns options to use when stapling the given system.

The following options are accepted:

:asdf --- The ASDF System object to generate. If this differs

from the argument to SYSTEM-OPTIONS, GENERATE is
called anew with the same arguments, but the system
being updated to the one in the options.
Defaults to the input system.
:compact --- Whether to compact (remove whitespace) from the
resulting documentation file.
Defaults to T.
:documentation --- The pathname to the primary documentation file to
output into the generated file’s documentation
section.
Defaults to FIND-DOCUMENTATION-FILE
:logo --- The relative path to a logo to include in the
generated file’s header.
Defaults to FIND-LOGO-FILE relative to the source

15
 directory of the system.
:name --- The name to use for the system.
Defaults to ASDF:COMPONENT-NAME
:out --- The pathname for the generated file.
Defaults to "about.html" relative to the source
directory of the system.
:packages --- The list of packages to output to the symbol index
in the generated file.
Defaults to SYSTEM-PACKAGES
:template --- The Clip template file to use to generate the
documentation file with.
Defaults to *DEFAULT-TEMPLATE*
:if-exists --- What to do if the generated file already exists on
the file system.
Defaults to :ERROR

These options may be overridden by the arguments that are passed to

GENERATE.

The methods are combined by APPEND, with the most specific method coming
first. This means that you can override certain options by creating a
method for your system and outputting a plist with the option you want
to override.

For example, the following method would specify an alternate template

file to use, and a different exists behaviour.

(defmethod staple:system-options append ((system (eql (asdf:find-system :my-sys))

(list :template (system-relative-pathname system "my-clip-template.ctml")
:if-exists :supersede))

You may specify additional arguments that are not shown above. They will
all be passed to Clip’s template generation, and may thus be accessed
from within the template.

See GENERATE
See FIND-DOCUMENTATION-FILE
See FIND-LOGO-FILE
See ASDF:COMPONENT-NAME
See ASDF:SYSTEM-SOURCE-DIRECTORY
See SYSTEM-PACKAGES
See *DEFAULT-TEMPLATE*
See CL:OPEN
– macro (

16
 DEFINE-CONVERTER
NAME ARGS &BODY BODY)
Shorthand to easily define a converter function.

See CONVERTER
macro (

DEFINE-SIMPLE-CONVERTER
OBJECT-CLASS TEST)
– Shorthand for the most common definitions.
If TEST function passes, a single symbol object constructed from OBJECT-CLASS
is returned as a list.

17