Litterae

This is an example project of Litterae Common Lisp documentation system.

This repository is part of the https://github.com/cl-doc-systems 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:

https://cl-doc-systems.github.io/litterae/

About this example

This is a small library which 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 Litterae library.

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

Let's review features, provided by Litterae.

Pros & Cons

Pros

  • Litterae is pretty forward and uses README.md as the source.
  • Generated documentation looks really nice.
  • It autogenerates API reference.

Cons

  • It is not suited for large projects with lengthy documentation.
  • You have to copy CSS and other assets manually from LItterae's assets/ folder. Right now page's style is not so cool like it was when I've added style.css to the Teddy's documentation.
  • 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 Pygments Python library.
  • Table of contents does not show sections from the README file, only API reference.
  • It is impossible to reference HTML chapters because there is no HTML anchors for them.

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.

Litterae 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. For example we can reference FOO like this [`FOO`](#example-app:foo-10) and it will appear in the code as the link FOO. This is very inconvenient :(

API Documentation

Package: EXAMPLE/UTILS

Functions

concat ( first second )

This function is not exported and should not be showed in the API reference.

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.

Sandly, we can't reference parts of the documentation from README. I'd like to make a link to "Handwritten documentation" chapter but there is no HTML anchor there.

Package: EXAMPLE/CLASS

Classes

admin

Admins should have additional priveleges.

user

All users in the system have this class.

Last login slot is updated automatically.

Generic-function-node

is-admin ( user )

Returns t if user can modify the system.

Methods

is-admin ( ( user admin ) )

is-admin ( ( user user ) )

Package: EXAMPLE/APP

Macros

defrule ( name &body body )

This is a fake macro just to see if documentation system will be able to extract docstrings for NUMBER-ONE.

Variables

number-one

Functions

foo ( first &key ( other 100500 ) )

This is example function.

Internally it calls 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.