Example of CL-GENDOC documentation for a Common Lisp library

This is a small library includes a few functions with docstrings and a handwritten documentation. The purpose is to demonstrate core features of the cl-gendoc library.

The repository can be used as a template for new libraries if you've choosen cl-gendoc for documenting your library.

Let's review features, provided by cl-gendoc.

Pros & Cons of cl-gendoc

Pros

Markdown format is supported by default. It als can be used in docstrings.
Resulting HTML can be constructed from blocks of different types. By default, Markdown files and autogenerated package reference are supported.
You can write an extensions to support other markups.
Links to hyperspec from code snippets (if you download and unpack HyperSpec archive.

Cons

To create a multi-html documentation you have to write a function which will build each page separately.
There is no any default theme. But you can provide a single CSS file.
You can't adjust the way how HTML is generated, for example, to make an alternative template.
Cross reference is half-automated, cl-gendoc only generates HTML anchors for symbols, but don't provides a convenient way to reference them.
Header levels in documents and autogenerated reference are different.
There is no docstring deindentation and docstrings in code will look ugly :(
CLOS classes are not supported yet.

Handwritten documentation

I think the ability to write a large pieces of documentation which aren't bound to a function, class or module is an important feature. This way you can tell the user about some toplevel abstractions and give a bird eye view on the library or system.

For example, handwritten parts of the documentation can provide some code snippets to demonstrate the ways, how to use the library:


   (loop repeat 42
         collect (foo "bar" 100500))

And when you are talking about some function or class, you can reference it. But this referencing is manual. You have to contruct links using Markdown markup.

For example, if I'm talking about FOO function, I can reference it like this [`EXAMPLE/APP:FOO`](#apiref-foo) and it will appear in the code as the link EXAMPLE/APP:FOO. Pay attention that the link does not have a package name. It can be hard to use cl-gendoc do document a system containing multiple packages.

Also cl-gendoc will not warn you if you will have a typo in a link name. The link just will not work in the resulting documentation :(

It is also possible to refer documentation of packages. For example, here are docs for example/app package.

Autogenerated reference

Pay attention that cl-gendoc uses h1 for section below. But I'd like to use h3, to make it fit into the document structure.

Reference: EXAMPLE/APP

This is docstring for the package.

The package contains a function which does it's job by applying transformation to the first and second arguments.

CL-GENDOC does not support doctring deindentaion and this docstring looks ugly in the code :(

Functions

FOO

(FIRST &KEY (OTHER 100500))

This is example function.

Internally it calls EXAMPLE/UTILS:DO-THE-JOB to do the real job.

Reference: EXAMPLE/UTILS

Functions

DO-THE-JOB

(FIRST SECOND)

The function does the job.

It concatenates first and second arguments calling internal function concat.

On this multiline we'll check how does documentation system processes docstrings.

By the way, pay attention at the second paragraph where I've used Markdown format to make the word "concatenates" bold.