This tutorial goes through the process of documenting a Lisp project with Codex.

Getting Started

First, ceate a folder named docs in your project's root directory (the same directory as the ASDF file). There, you need to create two files: manifest.lisp and manual.scr.

The manifest.lisp file is read by Codex to figure out how to generate your docs, and in your case looks like this:

(:docstring-markup-format :scriba
 :systems (:my-library)
 :documents ((:title "My Library"
              :authors ("John Q. Lisper")
              :output-format (:type :multi-html
                              :template :minima)
              :sources ("manual.scr"))))

What this tells Codex is, mainly:

• Use Scriba to parse the docstrings.
• Before generating the docs, load and extract docstrings from the my-library system.
• Generate a document titled "My Library" from the manual.scr file.
• Write the document to mutiple HTML files using the Minima template.

The manual.scr file will be fairly bare-bones for now:

@begin(section)
@title(Overview)

My library does X, Y and Z.

@end(section)

Writing with Scriba

You can find the Scriba reference here.

Inserting API Documentation

To insert documentation of some Common Lisp construct – a function, class, macro, condition, etc. – you use the cl:with-package and cl:doc macros. For instance:

@cl:with-package[name="my-app"](
@cl:doc(function my-function)
@cl:doc(macro my-macro)
)

This tells Codex to find a function named my-function and a macro named my-macro in the my-app package, and insert their API documentation. In the case of functions and macros, the only documentation that is inserted is their name, lambda list and documentation string, but other objects have more complex API documentation. For instance, classes include documentatio strings for all their slots.

The cl:doc macro takes its arguments as a space-separated list of strings in the body. The first argument is the documentation type (e.g., "function" or "class"), and the second the symbol name of the thing to insert. For methods, you can add the lambda list of the method you want to insert. For example:

@cl:with-package[name="serialize-lib"](
@cl:doc(generic serialize)
@cl:doc(method serialize (object integer) stream)
@cl:doc(method serialize (object float) stream)
@cl:doc(method serialize (object string) stream)
)

Belows is the full list of API documentation types:

• function
• macro
• generic
• method
• variable
• struct
• class
• condition
• type
• cfunction
• ctype
• cstruct
• cunion
• cenum
• cbitfield

The documentation types prefixed with a 'c' refer to CFFI constructs, i.e., cfunction refers to a C function declared with CFFI's defcfun macro.

Docstrings

Codex parses documentation strings using the format you specify in the manifest with the :docstring-markup-format option. In this case, we've chosen Scriba, which means we can insert Scriba markup in docstrings. For example:

(defun download-website-text (url)
  "Downloads @cl:param(url) and strips all HTML tags."
  ...)

(defclass metal ()
  ((cost :reader cost
         :initarg cost
         :type float
         :documentation "All instances @b(must) initialize cost to a floating
         point value.")))

Linking to the CLHS

You can use the cl:spec macro to link to a part of the Common Lisp HyperSpec.

For example, the following:

@cl:spec(call-next-method)
@cl:spec(complex)

will produce links to call-next-method and complex.

Building

Finally, run (codex:document :my-system). You'll see some compilation output and a lot of lines with "Inserting documentation for...". When that's done, you can open the resulting HTML in your browser.