READMEmd[edit on web]


This is an example project of Eazy Documentation Common Lisp documentation system.

This repository is part of the organization, created to compare different Common Lisp documentation systems

The goal is make it easier for CL software developers to choose proper documentation system and to improve docs in their software!

Resulting documentation can be viewed here:

OSX Installation

brew install pandoc
brew install texinfo
export PATH="/usr/local/opt/texinfo/bin:$PATH"

;; Without this, eazy documentation will not find
;; ASDF system in the local directory:
export CL_SOURCE_REGISTRY=`pwd`/

ros install guicho271828/eazy-documentation

# Eazy Documentation is able to process
# package inferred systems only on ASDF >= 3.3.4
# That is why we need to upgrade it.
ros install asdf

Ubuntu Installation

For ubuntu, replace brew commands with:

sudo apt-get install pandoc texi2html


0 introductionrst[edit on web]

Example of Eazy Documentation for a Common Lisp library

This is a small library includes a few functions with docstrings and a documentation for the system and all included packages.

The purpose is to demonstrate core features of the eazy-documentation library.

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

Let's review features, provided by Eazy Documentation.

1 pros-n-consrst[edit on web]

Pros & Cons of Coo


  • Eazy documentation supports many markups out of the box:
    • docx
    • epub
    • man
    • markdown
    • md
    • mediawiki
    • odt
    • opml
    • org
    • rst
    • tex
    • texi
    • texinfo
    • text
    • textile
    • txt
    • wiki
  • By default, Markdown is used for docstrings.
  • And the system is able to do proper deindentation for docstrings.
  • It automatically discovers README and files in doc folder.
  • All lisp files are processed as documents and presented in the resulting HTML file as sections.
  • It is able to process docstrins in forms other than standard functions, macros, classes, etc.
  • Eazy documentation uses CommonDoc for internal document representation and theoretically you can write your own post-processing.
  • There is default color-theme.
  • Eazy documentation generates links to the source of every section. This way typos or small errors can be easily fixed on the GitHub. I really like this feature!
  • It generates a single HTML file which can be easily searched through in the browser.
  • Eazy documentation includes a command line utility and which be called to build documentation for any CL system loadable via ASDF.
  • It can be used to build documentation for non Lisp projects. Just point it to any directory with documentation files. For example, take a look at [this manual](manuals.html). However, this feature is only available in my fork and not merged to upstream yet.


  • There is only one way to control the order of files in the doc - to add a numberic prefix.
  • There is no cross-referencing is semi-automatic - you have to write links manually.
  • And there is not autocheck if all links are correct.
  • You have to install pandoc and texinfo into the system :(
  • It will be hard to add additional markup to rst or markdown, because they are processed by pandoc.
  • I don't like default color theme, but you can redefine it.
  • Also I don't like how the document is rendered. Side-bar with files is OK, but different sizes of HTML headers in the main site's section looks ugly. Probably it is possible to use some header level normalization.
  • Seems package-inferred systems style is not supported fully, because I don't see EXAMPLE/APP and EXAMPLE/UTILS packages description in this document.
  • It generates a single HTML file which can be pretty large if your system is big.

3 handwrittenrst[edit on web]

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. For example, if I'm talking about foo function.

Eazy documentation does not provides an eazy way to refer symbols. It would be nice to have EXAMPLE/APP:FOO autolinked, but this does not work.

But the system generates HTML ids for symbols and you can refer them manually. The syntax will be different depending on file's markup language. In reStructured text we can reference FOO like this `FOO <#EXAMPLE/APP:FOO>`_ and it will appear in the code as the link FOO.

4 autogeneratedrst[edit on web]

Autogenerated API

As I said previously, Eazy Documentation processes Lisp files as a documents and all of them will be presented in the document as sections.

It has unique docstring extration algorithm, which is able to extract docstrings from forms which are not standard.

I've created an example for you:

(defmacro defrule (name &body body)
  "This is a fake macro just to demonstrate how eazy-documentation
   will extract docstrings from it's forms."
  `(defparameter ,name '(,@(rest body))))

(defrule number-one
    "This is a rule's docstring. Nothing special, just a text.

After macro-expansion it will be just:

   (defparameter number-one '((a b c)))

  (a b c))

Here is the resulting part of the documentation. Pay attention, there two blocks named defrule:number-one and defparameter:number-one, but both having the same HTML id EXAMPLE/APP:NUMBER-ONE. Because of this, you'll not be able to refer the defrule or the parameter separately. I like the concept of locatives from MGL-PAX, reviewed recently. They allow to select a type of an object you are referring to.

exampleasd[edit on web]


This description will be used only if long-description is missing


buildros[edit on web]


(documentation missing)


utilslisp[edit on web]

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. Also, we can reference some parts of the documentation. Read more about cross referencing in the [Handwritten documentation](#handwritten-documentation) chapter.

classlisp[edit on web]


All users in the system have this class. Last login slot is updated automatically.


Admins should have additional priveleges.

applisp[edit on web]

name &body body

This is a fake macro just to demonstrate how eazy-documentation will extract docstrings from it's forms.


This is a rule's docstring. Nothing special, just a text. After macro-expansion it will be just: (defparameter number-one '((a b c)))


(documentation missing)

first &key (other 100500)

This is example function. Internally it calls [DO-THE-JOB](#EXAMPLE/UTILS:DO-THE-JOB) to do the real job. Note, I'm using Markdown in this doctring. This is default and docstrings markup can be changed by a parameter.